From adee0e5ef6faf5ae887161e66b14fdab7348ee05 Mon Sep 17 00:00:00 2001 From: Rithvik Doshi Date: Tue, 24 Feb 2026 11:50:42 -0500 Subject: [PATCH 1/8] feat: add agents.md --- AGENTS.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8fe0d3b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,75 @@ +# SEMOSS Template App Development + +This file provides necessary context for agents to interact with, use, build and deploy SEMOSS Template Applications + +## Project overview +- What this project does: starter template for SEMOSS React apps with Java reactors, build tooling, and example UI/components. +- Primary users: SEMOSS app developers building pro-code apps (React + Java) and MCPs using the template app. +- Non-goals: drag-and-drop SEMOSS apps or standalone web apps outside SEMOSS. + +## Architecture +- Key modules/packages and their purpose: `client` for React/Vite app, `java` for custom reactors, `classes` for compiled outputs, `portals` for published UI. +- Data flow or request lifecycle: React UI in `client` builds to `portals` and is published via the SEMOSS UI; Java reactors compile into `classes` via SEMOSS. +- External services or integrations: SEMOSS SDK (`@semoss/sdk`) and SEMOSS runtime. + +## Development workflow +- Required tools or versions: Java 21 (Maven compiler target), Node + pnpm, Python (used in linting pipeline). +- Package manager(s): pnpm (front-end), Maven (Java). +- Common commands: `pnpm i` (root and `client`), `pnpm dev` (root), `pnpm build` (root), `pnpm fix` (root), `pnpm javadoc` (root); check package.json for any additional commands added +- Environment setup steps: create `client/.env.local` with `CLIENT_APP="your-app-id"`; create blank `java/project.properties` in the `client` folder if you plan on adding backend env vars. +- Adding project to eclipse: ensure you change the group and project id in the `pom.xml` to whatever necessary identifiers; select Import, Existing Maven Project, select the base directory of the repo, and add that. +- When changes are made to the codebase, ensure we publish and compile the code on the Semoss platform itself. + +## Code conventions +- Style rules or linters: Biome for formatting and linting; lint-staged + husky pre-commit. +- Naming conventions: follow React/TypeScript and Java conventions as in existing examples. +- Testing approach: Java tests under `test/` with JUnit; see `test/README.md`. +- Logging and error handling: follow existing Java reactor patterns; use SEMOSS error types where applicable. + +## Frontend notes (if applicable) +- Design system or component library: shadcn/ui + Radix UI primitives, Tailwind CSS. +- State management: React context in `client/src/contexts`. +- Routing: `react-router-dom` with routes in `client/src/pages`. +- Accessibility requirements: follow Radix/shadcn defaults; keep interactive components keyboard accessible. + +## Backend notes (if applicable) +- API style (REST/GraphQL/etc.): SEMOSS reactors (Java classes under `java/src/reactors`) that are compiled at runtime by SEMOSS. +- Authn/Authz: handled by SEMOSS runtime. +- Database and migrations: managed by SEMOSS; not configured in this template. +- Background jobs or queues: none in template. + +## MCP development +- MCP manifests: `mcp/pixel_mcp.json` (Java reactors) and `mcp/py_mcp.json` (Python tools). These are generated by reactor calls - don't edit/create these manually. + +### Java MCP servers +- Create an abstract project reactor under `java/src/reactors`, define `keysToGet`/`keyRequired`, and implement `doExecute()`, `getReactorDescription()`, `getKeyTypeForMCP()`, `getDescriptionForKey()` as those are necessary metadata for the server definition. +- Generate the MCP manifest by running the SEMOSS reactor that builds `mcp/pixel_mcp.json` from the selected reactors (see `MakePixelMCPReactor` in SEMOSS core). + +### Python MCP servers +- Add tool functions to `py/mcp_driver.py` (preferred name; legacy `py/smss_driver.py` is supported but should be avoided). +- The functions added should only be the end tools you want to expose. Any helper methods added there will be picked up as tools, so don't do that if not intended. +- If extra metadata needs to be passed, use the decorator `@mcp_metadata`. Usage: + - Decorator factory to add metadata to MCP functions. + - Usage: `@mcp_metadata({'loadingMessage': 'Loading...', 'resourceURI': null, 'execution':'auto'|'ask'|'disabled', 'displayLocation': 'inline'|'sidebar'|'hidden'})` +- The `ROOT` variable is injected into the `mcp_driver.py` file and is the path to the current insight folder. For an MCP, it is effectively the room folder path. You will have to manually propagate this to any dependencies. +- Use the SEMOSS reactor that converts the python driver file into an MCP tool to update `mcp/py_mcp.json` (see `MakePythonMCPReactor` in SEMOSS core). + +### Instantiation (How this works) +- The MCP server is created through `InitMCPReactor`, which calls `MCPFactory.build(engine)` and returns `mcp.initMCP(protocolVersion)`. +- Java tools are instantiated by reading `mcp/pixel_mcp.json` and binding reactor names to tools via `AbstractReactor.asMcpTool()`. +- Python tools execute by importing `mcp_driver` and calling the function with resolved parameters (see `MCPUtility.runPythonTool`). + +## File/dir pointers +- Important entry points: `portals/index.html` (published entry), `client/src/index.tsx` (app entry), `client/src/App.tsx`. +- Configuration files: `client/vite.config.ts`, `client/tailwind.config.js`, `biome.json`, `pom.xml`. +- Generated or vendor directories to avoid: `portals/` (build output), `classes/`, `target/`. + +## Do and don't +- Preferred patterns: keep UI code in `client`, custom logic in Java reactors, publish via SEMOSS UI after build. +- Avoided patterns: editing built files directly in `portals/`. +- Performance or security gotchas: remember to publish files in SEMOSS UI; avoid committing secrets to `.env.local`; remember to add backend environment variables to `java/project.properties` and integrate into the codebase. + +## Release and deployment +- Environments: local SEMOSS instance for development; to build for Semoss upload, zip the java folder, built portals, any other metadata files/folders that are important. +- CI/CD details: not defined in template. +- Manual steps: run `pnpm build`, then use SEMOSS UI Publish Files. From a9ee054d632d6dec8fb9993c2a51629b02e2efd6 Mon Sep 17 00:00:00 2001 From: Rithvik Doshi Date: Tue, 24 Feb 2026 14:36:42 -0500 Subject: [PATCH 2/8] docs: docs --- AGENTS.md | 43 +++++++++++++++++++------------------------ 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8fe0d3b..19df884 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,24 +1,24 @@ # SEMOSS Template App Development -This file provides necessary context for agents to interact with, use, build and deploy SEMOSS Template Applications - -## Project overview -- What this project does: starter template for SEMOSS React apps with Java reactors, build tooling, and example UI/components. -- Primary users: SEMOSS app developers building pro-code apps (React + Java) and MCPs using the template app. -- Non-goals: drag-and-drop SEMOSS apps or standalone web apps outside SEMOSS. +This file provides context for agents to use, build, and deploy the SEMOSS template app. It is a starter template for SEMOSS React apps with Java reactors, build tooling, and example UI/components. Primary users are SEMOSS app developers building pro-code apps (React + Java) and MCPs using the template app. Non-goals include drag-and-drop SEMOSS apps or standalone web apps outside SEMOSS. ## Architecture -- Key modules/packages and their purpose: `client` for React/Vite app, `java` for custom reactors, `classes` for compiled outputs, `portals` for published UI. -- Data flow or request lifecycle: React UI in `client` builds to `portals` and is published via the SEMOSS UI; Java reactors compile into `classes` via SEMOSS. +- Key modules/packages and their purpose: `client` for React/Vite app, `java` for custom reactors, `classes` for compiled outputs, `portals` for published UI, `mcp` for generated MCP manifests, `py` for Python MCP tools. +- Data flow: React UI in `client` builds to `portals` and is published via the SEMOSS UI; the UI calls reactors or MCP tools and returns data to the client; Java reactors compile into `classes` via SEMOSS. +- Frontend notes: shadcn/ui + Radix UI primitives + Tailwind CSS; React context in `client/src/contexts`; `react-router-dom` routes in `client/src/pages`; keep interactive components keyboard accessible. +- Backend notes: SEMOSS reactors under `java/src/reactors` compiled at runtime; Authn/Authz handled by SEMOSS; database and migrations are managed by SEMOSS; no background jobs in this template. - External services or integrations: SEMOSS SDK (`@semoss/sdk`) and SEMOSS runtime. ## Development workflow - Required tools or versions: Java 21 (Maven compiler target), Node + pnpm, Python (used in linting pipeline). - Package manager(s): pnpm (front-end), Maven (Java). - Common commands: `pnpm i` (root and `client`), `pnpm dev` (root), `pnpm build` (root), `pnpm fix` (root), `pnpm javadoc` (root); check package.json for any additional commands added + - When changes are made to the client folder, the user may need to rebuild and republish the app, otherwise changes made may not show up. - Environment setup steps: create `client/.env.local` with `CLIENT_APP="your-app-id"`; create blank `java/project.properties` in the `client` folder if you plan on adding backend env vars. - Adding project to eclipse: ensure you change the group and project id in the `pom.xml` to whatever necessary identifiers; select Import, Existing Maven Project, select the base directory of the repo, and add that. - When changes are made to the codebase, ensure we publish and compile the code on the Semoss platform itself. +- If `portals/` is missing or incomplete, run `pnpm i` and `pnpm build` at the repo root to regenerate the front-end bundle. +- If MCP tools exist for build/compile/publish actions, use those tools instead of manual instance troubleshooting steps. ## Code conventions - Style rules or linters: Biome for formatting and linting; lint-staged + husky pre-commit. @@ -26,17 +26,11 @@ This file provides necessary context for agents to interact with, use, build and - Testing approach: Java tests under `test/` with JUnit; see `test/README.md`. - Logging and error handling: follow existing Java reactor patterns; use SEMOSS error types where applicable. -## Frontend notes (if applicable) -- Design system or component library: shadcn/ui + Radix UI primitives, Tailwind CSS. -- State management: React context in `client/src/contexts`. -- Routing: `react-router-dom` with routes in `client/src/pages`. -- Accessibility requirements: follow Radix/shadcn defaults; keep interactive components keyboard accessible. - -## Backend notes (if applicable) -- API style (REST/GraphQL/etc.): SEMOSS reactors (Java classes under `java/src/reactors`) that are compiled at runtime by SEMOSS. -- Authn/Authz: handled by SEMOSS runtime. -- Database and migrations: managed by SEMOSS; not configured in this template. -- Background jobs or queues: none in template. +## References (if needed) +- Semoss Repo: https://github.com/SEMOSS/Semoss (most important) + - SEMOSS docs folder for setup guidance: https://github.com/SEMOSS/Semoss/tree/main/docs +- Monolith Repo: https://github.com/SEMOSS/Monolith +- Semoss UI Repo: https://github.com/SEMOSS/semoss-ui ## MCP development - MCP manifests: `mcp/pixel_mcp.json` (Java reactors) and `mcp/py_mcp.json` (Python tools). These are generated by reactor calls - don't edit/create these manually. @@ -47,8 +41,8 @@ This file provides necessary context for agents to interact with, use, build and ### Python MCP servers - Add tool functions to `py/mcp_driver.py` (preferred name; legacy `py/smss_driver.py` is supported but should be avoided). -- The functions added should only be the end tools you want to expose. Any helper methods added there will be picked up as tools, so don't do that if not intended. -- If extra metadata needs to be passed, use the decorator `@mcp_metadata`. Usage: +- The functions added should only be the end tools you want to expose. Any function in the driver file is treated as a tool, so move helper logic into a separate helper module/file and import it instead. +- If extra metadata needs to be passed, use the decorator `@mcp_metadata` from `smssutil.py`. Usage: - Decorator factory to add metadata to MCP functions. - Usage: `@mcp_metadata({'loadingMessage': 'Loading...', 'resourceURI': null, 'execution':'auto'|'ask'|'disabled', 'displayLocation': 'inline'|'sidebar'|'hidden'})` - The `ROOT` variable is injected into the `mcp_driver.py` file and is the path to the current insight folder. For an MCP, it is effectively the room folder path. You will have to manually propagate this to any dependencies. @@ -67,9 +61,10 @@ This file provides necessary context for agents to interact with, use, build and ## Do and don't - Preferred patterns: keep UI code in `client`, custom logic in Java reactors, publish via SEMOSS UI after build. - Avoided patterns: editing built files directly in `portals/`. -- Performance or security gotchas: remember to publish files in SEMOSS UI; avoid committing secrets to `.env.local`; remember to add backend environment variables to `java/project.properties` and integrate into the codebase. +- Performance or security gotchas: remember to pnpm build then publish files in SEMOSS UI; avoid committing secrets to `.env.local`; remember to add backend environment variables to `java/project.properties` and integrate into the codebase. ## Release and deployment -- Environments: local SEMOSS instance for development; to build for Semoss upload, zip the java folder, built portals, any other metadata files/folders that are important. -- CI/CD details: not defined in template. +- Environments: local SEMOSS instance for development; for deployment, zip from `assets/` and include `portals/`, `java/`, `classes/` (if compiled), `mcp/`, plus config files you rely on (for example `pom.xml`, `package.json`, `pnpm-lock.yaml`, `biome.json`). +- Exclude `node_modules/`, `target/`, and local caches from the deployment zip. +- CI/CD details: before committing, ensure that husky is installed (run `pnpm i` in the root directory), and that the defined hooks are running. - Manual steps: run `pnpm build`, then use SEMOSS UI Publish Files. From 68cfa8c6c6066285c31bca084b2f8c235019371c Mon Sep 17 00:00:00 2001 From: Rithvik Doshi Date: Tue, 24 Feb 2026 14:53:46 -0500 Subject: [PATCH 3/8] docs: docs --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 19df884..52a4da3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,7 @@ This file provides context for agents to use, build, and deploy the SEMOSS templ ### Python MCP servers - Add tool functions to `py/mcp_driver.py` (preferred name; legacy `py/smss_driver.py` is supported but should be avoided). - The functions added should only be the end tools you want to expose. Any function in the driver file is treated as a tool, so move helper logic into a separate helper module/file and import it instead. +- Add Python docstrings to each tool function. These docstrings are used to derive tool descriptions and provide context to agents and UI surfaces. Keep them concise but specific: describe what the tool does, expected inputs, and what it returns. - If extra metadata needs to be passed, use the decorator `@mcp_metadata` from `smssutil.py`. Usage: - Decorator factory to add metadata to MCP functions. - Usage: `@mcp_metadata({'loadingMessage': 'Loading...', 'resourceURI': null, 'execution':'auto'|'ask'|'disabled', 'displayLocation': 'inline'|'sidebar'|'hidden'})` From 7f8097bf46250d493d42057e1e34a0b97455c55a Mon Sep 17 00:00:00 2001 From: Rithvik Doshi Date: Tue, 24 Feb 2026 15:30:19 -0500 Subject: [PATCH 4/8] docs: docs --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 52a4da3..c8939c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,13 @@ This file provides context for agents to use, build, and deploy the SEMOSS templ - The `ROOT` variable is injected into the `mcp_driver.py` file and is the path to the current insight folder. For an MCP, it is effectively the room folder path. You will have to manually propagate this to any dependencies. - Use the SEMOSS reactor that converts the python driver file into an MCP tool to update `mcp/py_mcp.json` (see `MakePythonMCPReactor` in SEMOSS core). +### MCP UI + tool execution notes +- The custom MCP UI should be tied to a specific tool name (from `py/mcp_driver.py` or a reactor), so the UI knows which tool to execute and which response to send back. +- Execute the tool from the UI with `actions.runMCPTool(name, params)` to ensure the MCP workflow and metadata are respected. +- After receiving the tool response, forward it to Playground with `sendMCPResponseToPlayground` so the tool call completes in the chat. +- `GetInsightAssets` throws if a file does not exist. Use `BrowseInsightAssets` first and only read files that are present (or handle missing files gracefully). +- Tool outputs can be single-encoded JSON strings or double-encoded JSON. Client-side parsing should handle both forms. + ### Instantiation (How this works) - The MCP server is created through `InitMCPReactor`, which calls `MCPFactory.build(engine)` and returns `mcp.initMCP(protocolVersion)`. - Java tools are instantiated by reading `mcp/pixel_mcp.json` and binding reactor names to tools via `AbstractReactor.asMcpTool()`. From dabe8ed096a4ac9fd8e878f1f15ce080e8703de0 Mon Sep 17 00:00:00 2001 From: Rithvik Doshi Date: Tue, 24 Feb 2026 16:00:06 -0500 Subject: [PATCH 5/8] docs: docs --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index c8939c5..bdc44d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,9 +43,11 @@ This file provides context for agents to use, build, and deploy the SEMOSS templ - Add tool functions to `py/mcp_driver.py` (preferred name; legacy `py/smss_driver.py` is supported but should be avoided). - The functions added should only be the end tools you want to expose. Any function in the driver file is treated as a tool, so move helper logic into a separate helper module/file and import it instead. - Add Python docstrings to each tool function. These docstrings are used to derive tool descriptions and provide context to agents and UI surfaces. Keep them concise but specific: describe what the tool does, expected inputs, and what it returns. -- If extra metadata needs to be passed, use the decorator `@mcp_metadata` from `smssutil.py`. Usage: +- CRITICAL: Any tool exposed from the driver should include the `@mcp_metadata` decorator from `smssutil.py` if we need to specify extra metadata. Do not expose a tool without it. +- Use the decorator `@mcp_metadata` from `smssutil.py` to set tool metadata. Usage: - Decorator factory to add metadata to MCP functions. - Usage: `@mcp_metadata({'loadingMessage': 'Loading...', 'resourceURI': null, 'execution':'auto'|'ask'|'disabled', 'displayLocation': 'inline'|'sidebar'|'hidden'})` + - If a ui is created for this tool, you can link it with resourceURI, otherwise if you don't use that/leave it null it will use a default mcp ui - The `ROOT` variable is injected into the `mcp_driver.py` file and is the path to the current insight folder. For an MCP, it is effectively the room folder path. You will have to manually propagate this to any dependencies. - Use the SEMOSS reactor that converts the python driver file into an MCP tool to update `mcp/py_mcp.json` (see `MakePythonMCPReactor` in SEMOSS core). From f6f7f6318c9f1a643308bdca9bcfc535e20749b2 Mon Sep 17 00:00:00 2001 From: Rithvik Doshi Date: Tue, 24 Feb 2026 16:06:20 -0500 Subject: [PATCH 6/8] docs: condense --- AGENTS.md | 113 +++++++++++++++++++++++++----------------------------- 1 file changed, 53 insertions(+), 60 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bdc44d4..af5238b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,80 +1,73 @@ # SEMOSS Template App Development -This file provides context for agents to use, build, and deploy the SEMOSS template app. It is a starter template for SEMOSS React apps with Java reactors, build tooling, and example UI/components. Primary users are SEMOSS app developers building pro-code apps (React + Java) and MCPs using the template app. Non-goals include drag-and-drop SEMOSS apps or standalone web apps outside SEMOSS. +Quick reference for building SEMOSS React apps with Java reactors and MCP tooling. Intended for SEMOSS pro-code apps and MCPs; not for drag-and-drop apps or standalone web deployments. ## Architecture -- Key modules/packages and their purpose: `client` for React/Vite app, `java` for custom reactors, `classes` for compiled outputs, `portals` for published UI, `mcp` for generated MCP manifests, `py` for Python MCP tools. -- Data flow: React UI in `client` builds to `portals` and is published via the SEMOSS UI; the UI calls reactors or MCP tools and returns data to the client; Java reactors compile into `classes` via SEMOSS. -- Frontend notes: shadcn/ui + Radix UI primitives + Tailwind CSS; React context in `client/src/contexts`; `react-router-dom` routes in `client/src/pages`; keep interactive components keyboard accessible. -- Backend notes: SEMOSS reactors under `java/src/reactors` compiled at runtime; Authn/Authz handled by SEMOSS; database and migrations are managed by SEMOSS; no background jobs in this template. -- External services or integrations: SEMOSS SDK (`@semoss/sdk`) and SEMOSS runtime. +- Key modules: `client` (React/Vite UI), `java` (custom reactors), `classes` (compiled reactors), `portals` (published UI), `mcp` (generated manifests), `py` (Python MCP tools). +- Flow: UI in `client` builds to `portals` and publishes via SEMOSS UI. UI calls reactors or MCP tools and returns data to the client. Reactors compile into `classes` at runtime. +- Frontend: shadcn/ui + Radix + Tailwind, contexts in `client/src/contexts`, routes in `client/src/pages`, keep components keyboard accessible. +- Backend: reactors under `java/src/reactors`; Authn/Authz, DB, and migrations managed by SEMOSS; no background jobs in this template. +- Integrations: SEMOSS SDK (`@semoss/sdk`) and SEMOSS runtime. ## Development workflow -- Required tools or versions: Java 21 (Maven compiler target), Node + pnpm, Python (used in linting pipeline). -- Package manager(s): pnpm (front-end), Maven (Java). -- Common commands: `pnpm i` (root and `client`), `pnpm dev` (root), `pnpm build` (root), `pnpm fix` (root), `pnpm javadoc` (root); check package.json for any additional commands added - - When changes are made to the client folder, the user may need to rebuild and republish the app, otherwise changes made may not show up. -- Environment setup steps: create `client/.env.local` with `CLIENT_APP="your-app-id"`; create blank `java/project.properties` in the `client` folder if you plan on adding backend env vars. -- Adding project to eclipse: ensure you change the group and project id in the `pom.xml` to whatever necessary identifiers; select Import, Existing Maven Project, select the base directory of the repo, and add that. -- When changes are made to the codebase, ensure we publish and compile the code on the Semoss platform itself. -- If `portals/` is missing or incomplete, run `pnpm i` and `pnpm build` at the repo root to regenerate the front-end bundle. -- If MCP tools exist for build/compile/publish actions, use those tools instead of manual instance troubleshooting steps. +- Required tools: Java 21, Node + pnpm, Python (linting pipeline). +- Package managers: pnpm (frontend), Maven (Java). +- Common commands (root unless noted): `pnpm i` (root and `client`), `pnpm dev`, `pnpm build`, `pnpm fix`, `pnpm javadoc`. +- Env setup: create `client/.env.local` with `CLIENT_APP="your-app-id"`; add `java/project.properties` (in `client`) if backend env vars are needed. +- Eclipse import: update group/project id in `pom.xml`, then Import -> Existing Maven Project. +- Publish/compile: after changes, build and publish via SEMOSS UI; if `portals/` is missing, run `pnpm i` and `pnpm build` at client folder root. +- If MCP build/compile/publish tools exist, prefer them over manual troubleshooting. ## Code conventions -- Style rules or linters: Biome for formatting and linting; lint-staged + husky pre-commit. -- Naming conventions: follow React/TypeScript and Java conventions as in existing examples. -- Testing approach: Java tests under `test/` with JUnit; see `test/README.md`. -- Logging and error handling: follow existing Java reactor patterns; use SEMOSS error types where applicable. - -## References (if needed) -- Semoss Repo: https://github.com/SEMOSS/Semoss (most important) - - SEMOSS docs folder for setup guidance: https://github.com/SEMOSS/Semoss/tree/main/docs -- Monolith Repo: https://github.com/SEMOSS/Monolith -- Semoss UI Repo: https://github.com/SEMOSS/semoss-ui +- Lint/format: Biome; lint-staged + husky pre-commit. +- Conventions: follow existing React/TypeScript and Java patterns. +- Tests: JUnit under `test/` (see `test/README.md`). +- Errors/logging: follow reactor patterns; use SEMOSS error types. ## MCP development -- MCP manifests: `mcp/pixel_mcp.json` (Java reactors) and `mcp/py_mcp.json` (Python tools). These are generated by reactor calls - don't edit/create these manually. +- Manifests: `mcp/pixel_mcp.json` (Java) and `mcp/py_mcp.json` (Python) are generated by reactors. Do not edit manually. ### Java MCP servers -- Create an abstract project reactor under `java/src/reactors`, define `keysToGet`/`keyRequired`, and implement `doExecute()`, `getReactorDescription()`, `getKeyTypeForMCP()`, `getDescriptionForKey()` as those are necessary metadata for the server definition. -- Generate the MCP manifest by running the SEMOSS reactor that builds `mcp/pixel_mcp.json` from the selected reactors (see `MakePixelMCPReactor` in SEMOSS core). +- Create an abstract project reactor under `java/src/reactors` and implement: `keysToGet`, `keyRequired`, `doExecute()`, `getReactorDescription()`, `getKeyTypeForMCP()`, `getDescriptionForKey()`. +- Generate `mcp/pixel_mcp.json` via the SEMOSS reactor (see `MakePixelMCPReactor`). ### Python MCP servers -- Add tool functions to `py/mcp_driver.py` (preferred name; legacy `py/smss_driver.py` is supported but should be avoided). -- The functions added should only be the end tools you want to expose. Any function in the driver file is treated as a tool, so move helper logic into a separate helper module/file and import it instead. -- Add Python docstrings to each tool function. These docstrings are used to derive tool descriptions and provide context to agents and UI surfaces. Keep them concise but specific: describe what the tool does, expected inputs, and what it returns. -- CRITICAL: Any tool exposed from the driver should include the `@mcp_metadata` decorator from `smssutil.py` if we need to specify extra metadata. Do not expose a tool without it. -- Use the decorator `@mcp_metadata` from `smssutil.py` to set tool metadata. Usage: - - Decorator factory to add metadata to MCP functions. - - Usage: `@mcp_metadata({'loadingMessage': 'Loading...', 'resourceURI': null, 'execution':'auto'|'ask'|'disabled', 'displayLocation': 'inline'|'sidebar'|'hidden'})` - - If a ui is created for this tool, you can link it with resourceURI, otherwise if you don't use that/leave it null it will use a default mcp ui -- The `ROOT` variable is injected into the `mcp_driver.py` file and is the path to the current insight folder. For an MCP, it is effectively the room folder path. You will have to manually propagate this to any dependencies. -- Use the SEMOSS reactor that converts the python driver file into an MCP tool to update `mcp/py_mcp.json` (see `MakePythonMCPReactor` in SEMOSS core). +- Add tools to `py/mcp_driver.py` (preferred; avoid `py/smss_driver.py`). Only expose end tools; move helpers to separate modules. +- Add concise docstrings that describe behavior, inputs, and outputs. +- CRITICAL: every tool must use `@mcp_metadata` from `smssutil.py`. +- `@mcp_metadata` usage: `@mcp_metadata({'loadingMessage': 'Loading...', 'resourceURI': null, 'execution': 'auto'|'ask'|'disabled', 'displayLocation': 'inline'|'sidebar'|'hidden'})`. +- `ROOT` is injected into `mcp_driver.py`; propagate it to dependencies. +- Generate `mcp/py_mcp.json` via the SEMOSS reactor (see `MakePythonMCPReactor`). -### MCP UI + tool execution notes -- The custom MCP UI should be tied to a specific tool name (from `py/mcp_driver.py` or a reactor), so the UI knows which tool to execute and which response to send back. -- Execute the tool from the UI with `actions.runMCPTool(name, params)` to ensure the MCP workflow and metadata are respected. -- After receiving the tool response, forward it to Playground with `sendMCPResponseToPlayground` so the tool call completes in the chat. -- `GetInsightAssets` throws if a file does not exist. Use `BrowseInsightAssets` first and only read files that are present (or handle missing files gracefully). -- Tool outputs can be single-encoded JSON strings or double-encoded JSON. Client-side parsing should handle both forms. +### MCP UI + execution +- UI must target a specific tool name (reactor or `mcp_driver.py`). +- Execute with `actions.runMCPTool(name, params)` and forward results with `sendMCPResponseToPlayground`. +- `GetInsightAssets` throws on missing files; call `BrowseInsightAssets` first or handle missing files. +- Tool output may be single- or double-encoded JSON; handle both. -### Instantiation (How this works) -- The MCP server is created through `InitMCPReactor`, which calls `MCPFactory.build(engine)` and returns `mcp.initMCP(protocolVersion)`. -- Java tools are instantiated by reading `mcp/pixel_mcp.json` and binding reactor names to tools via `AbstractReactor.asMcpTool()`. -- Python tools execute by importing `mcp_driver` and calling the function with resolved parameters (see `MCPUtility.runPythonTool`). +### MCP instantiation +- Init: `InitMCPReactor` -> `MCPFactory.build(engine)` -> `mcp.initMCP(protocolVersion)`. +- Java tools bind from `mcp/pixel_mcp.json` via `AbstractReactor.asMcpTool()`. +- Python tools run by importing `mcp_driver` (see `MCPUtility.runPythonTool`). -## File/dir pointers -- Important entry points: `portals/index.html` (published entry), `client/src/index.tsx` (app entry), `client/src/App.tsx`. -- Configuration files: `client/vite.config.ts`, `client/tailwind.config.js`, `biome.json`, `pom.xml`. -- Generated or vendor directories to avoid: `portals/` (build output), `classes/`, `target/`. +## File pointers +- Entry points: `portals/index.html`, `client/src/index.tsx`, `client/src/App.tsx`. +- Config: `client/vite.config.ts`, `client/tailwind.config.js`, `biome.json`, `pom.xml`. +- Generated: avoid direct edits to `portals/`, `classes/`, `target/`. -## Do and don't -- Preferred patterns: keep UI code in `client`, custom logic in Java reactors, publish via SEMOSS UI after build. -- Avoided patterns: editing built files directly in `portals/`. -- Performance or security gotchas: remember to pnpm build then publish files in SEMOSS UI; avoid committing secrets to `.env.local`; remember to add backend environment variables to `java/project.properties` and integrate into the codebase. +## Do and do not +- Do: keep UI in `client`, custom logic in Java reactors, build then publish via SEMOSS UI. +- Do not: edit built assets in `portals/`. +- Reminders: avoid committing secrets in `.env.local`; add backend env vars to `java/project.properties` and wire them in code. ## Release and deployment -- Environments: local SEMOSS instance for development; for deployment, zip from `assets/` and include `portals/`, `java/`, `classes/` (if compiled), `mcp/`, plus config files you rely on (for example `pom.xml`, `package.json`, `pnpm-lock.yaml`, `biome.json`). -- Exclude `node_modules/`, `target/`, and local caches from the deployment zip. -- CI/CD details: before committing, ensure that husky is installed (run `pnpm i` in the root directory), and that the defined hooks are running. -- Manual steps: run `pnpm build`, then use SEMOSS UI Publish Files. +- Dev: local SEMOSS instance. +- Deploy zip from `assets/`: include `portals/`, `java/`, `classes/` (if compiled), `mcp/`, plus needed config files (for example `pom.xml`, `package.json`, `pnpm-lock.yaml`, `biome.json`). +- Exclude `node_modules/`, `target/`, and local caches. +- CI/CD: ensure husky is installed (`pnpm i` at repo root) and hooks are active. +- Manual step: `pnpm build`, then SEMOSS UI Publish Files. + +## References +- https://github.com/SEMOSS/Semoss (docs: https://github.com/SEMOSS/Semoss/tree/main/docs) +- https://github.com/SEMOSS/Monolith +- https://github.com/SEMOSS/semoss-ui From bf00322ecd31535e7054879167a2d61351be2156 Mon Sep 17 00:00:00 2001 From: Rithvik Doshi Date: Tue, 24 Feb 2026 16:07:55 -0500 Subject: [PATCH 7/8] docs: docs --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index af5238b..8813567 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,7 +41,7 @@ Quick reference for building SEMOSS React apps with Java reactors and MCP toolin ### MCP UI + execution - UI must target a specific tool name (reactor or `mcp_driver.py`). -- Execute with `actions.runMCPTool(name, params)` and forward results with `sendMCPResponseToPlayground`. +- CRITICAL: Execute tools with `actions.runMCPTool(name, params)`, the tool must forward results with `actions.sendMCPResponseToPlayground` in order to "finish" execution. - `GetInsightAssets` throws on missing files; call `BrowseInsightAssets` first or handle missing files. - Tool output may be single- or double-encoded JSON; handle both. From 5b9a9ac4a00d6ef3a9e1158f16b8937ab2dcab88 Mon Sep 17 00:00:00 2001 From: Tejas Lokeshrao Date: Wed, 25 Feb 2026 15:55:56 -0500 Subject: [PATCH 8/8] fix: updated agents.md --- AGENTS.md | 350 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 277 insertions(+), 73 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8813567..397c6da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,73 +1,277 @@ -# SEMOSS Template App Development - -Quick reference for building SEMOSS React apps with Java reactors and MCP tooling. Intended for SEMOSS pro-code apps and MCPs; not for drag-and-drop apps or standalone web deployments. - -## Architecture -- Key modules: `client` (React/Vite UI), `java` (custom reactors), `classes` (compiled reactors), `portals` (published UI), `mcp` (generated manifests), `py` (Python MCP tools). -- Flow: UI in `client` builds to `portals` and publishes via SEMOSS UI. UI calls reactors or MCP tools and returns data to the client. Reactors compile into `classes` at runtime. -- Frontend: shadcn/ui + Radix + Tailwind, contexts in `client/src/contexts`, routes in `client/src/pages`, keep components keyboard accessible. -- Backend: reactors under `java/src/reactors`; Authn/Authz, DB, and migrations managed by SEMOSS; no background jobs in this template. -- Integrations: SEMOSS SDK (`@semoss/sdk`) and SEMOSS runtime. - -## Development workflow -- Required tools: Java 21, Node + pnpm, Python (linting pipeline). -- Package managers: pnpm (frontend), Maven (Java). -- Common commands (root unless noted): `pnpm i` (root and `client`), `pnpm dev`, `pnpm build`, `pnpm fix`, `pnpm javadoc`. -- Env setup: create `client/.env.local` with `CLIENT_APP="your-app-id"`; add `java/project.properties` (in `client`) if backend env vars are needed. -- Eclipse import: update group/project id in `pom.xml`, then Import -> Existing Maven Project. -- Publish/compile: after changes, build and publish via SEMOSS UI; if `portals/` is missing, run `pnpm i` and `pnpm build` at client folder root. -- If MCP build/compile/publish tools exist, prefer them over manual troubleshooting. - -## Code conventions -- Lint/format: Biome; lint-staged + husky pre-commit. -- Conventions: follow existing React/TypeScript and Java patterns. -- Tests: JUnit under `test/` (see `test/README.md`). -- Errors/logging: follow reactor patterns; use SEMOSS error types. - -## MCP development -- Manifests: `mcp/pixel_mcp.json` (Java) and `mcp/py_mcp.json` (Python) are generated by reactors. Do not edit manually. - -### Java MCP servers -- Create an abstract project reactor under `java/src/reactors` and implement: `keysToGet`, `keyRequired`, `doExecute()`, `getReactorDescription()`, `getKeyTypeForMCP()`, `getDescriptionForKey()`. -- Generate `mcp/pixel_mcp.json` via the SEMOSS reactor (see `MakePixelMCPReactor`). - -### Python MCP servers -- Add tools to `py/mcp_driver.py` (preferred; avoid `py/smss_driver.py`). Only expose end tools; move helpers to separate modules. -- Add concise docstrings that describe behavior, inputs, and outputs. -- CRITICAL: every tool must use `@mcp_metadata` from `smssutil.py`. -- `@mcp_metadata` usage: `@mcp_metadata({'loadingMessage': 'Loading...', 'resourceURI': null, 'execution': 'auto'|'ask'|'disabled', 'displayLocation': 'inline'|'sidebar'|'hidden'})`. -- `ROOT` is injected into `mcp_driver.py`; propagate it to dependencies. -- Generate `mcp/py_mcp.json` via the SEMOSS reactor (see `MakePythonMCPReactor`). - -### MCP UI + execution -- UI must target a specific tool name (reactor or `mcp_driver.py`). -- CRITICAL: Execute tools with `actions.runMCPTool(name, params)`, the tool must forward results with `actions.sendMCPResponseToPlayground` in order to "finish" execution. -- `GetInsightAssets` throws on missing files; call `BrowseInsightAssets` first or handle missing files. -- Tool output may be single- or double-encoded JSON; handle both. - -### MCP instantiation -- Init: `InitMCPReactor` -> `MCPFactory.build(engine)` -> `mcp.initMCP(protocolVersion)`. -- Java tools bind from `mcp/pixel_mcp.json` via `AbstractReactor.asMcpTool()`. -- Python tools run by importing `mcp_driver` (see `MCPUtility.runPythonTool`). - -## File pointers -- Entry points: `portals/index.html`, `client/src/index.tsx`, `client/src/App.tsx`. -- Config: `client/vite.config.ts`, `client/tailwind.config.js`, `biome.json`, `pom.xml`. -- Generated: avoid direct edits to `portals/`, `classes/`, `target/`. - -## Do and do not -- Do: keep UI in `client`, custom logic in Java reactors, build then publish via SEMOSS UI. -- Do not: edit built assets in `portals/`. -- Reminders: avoid committing secrets in `.env.local`; add backend env vars to `java/project.properties` and wire them in code. - -## Release and deployment -- Dev: local SEMOSS instance. -- Deploy zip from `assets/`: include `portals/`, `java/`, `classes/` (if compiled), `mcp/`, plus needed config files (for example `pom.xml`, `package.json`, `pnpm-lock.yaml`, `biome.json`). -- Exclude `node_modules/`, `target/`, and local caches. -- CI/CD: ensure husky is installed (`pnpm i` at repo root) and hooks are active. -- Manual step: `pnpm build`, then SEMOSS UI Publish Files. - -## References -- https://github.com/SEMOSS/Semoss (docs: https://github.com/SEMOSS/Semoss/tree/main/docs) -- https://github.com/SEMOSS/Monolith -- https://github.com/SEMOSS/semoss-ui +# SEMOSS MCP Tool Development + +Comprehensive guide for building SEMOSS MCP tools with custom UIs. + +--- + +## Quick Reference + +### Architecture +- **Key modules**: `client` (React/Vite UI), `portals` (published UI), `mcp` (generated manifests), `py` (Python MCP tools) +- **Flow**: UI in `client` builds to `portals` and publishes via SEMOSS UI. UI calls MCP tools via SDK and returns data to the client +- **Frontend**: shadcn/ui + Radix + Tailwind, contexts in `client/src/contexts`, routes in `client/src/pages`, keep components keyboard accessible +- **Integrations**: SEMOSS SDK (`@semoss/sdk`) and SEMOSS runtime + +### Development Workflow +1. **Setup**: Install Node + pnpm and Python +2. **Common commands**: + - `pnpm i` (root and `client`) + - `pnpm dev` (development server) + - `pnpm build` (production build) +3. **Environment**: Replace the app id in `client/.env` with: + ``` + APP="your-app-id" + ``` +4. **Publish**: After changes, build and publish via SEMOSS UI; if `portals/` is missing, run `pnpm i` and `pnpm build` at client folder root + +### MCP Development Basics +- **Manifests**: `mcp/py_mcp.json` (Python) is generated by reactors. Do not edit manually +- **Tools location**: Add tools to `py/mcp_driver.py`. Only expose end tools; move helpers to separate modules +- **Docstrings**: Add concise docstrings that describe behavior, inputs, and outputs +- **Metadata**: Every tool must use `@mcp_metadata` from `smssutil.py` +- **ROOT**: Injected into `mcp_driver.py`; propagate it to dependencies +- **smssutil**: The `smssutil` module (containing `@mcp_metadata`) is automatically injected by SEMOSS, similar to `ROOT`. You don't need to create it +- **Generation**: Generate `mcp/py_mcp.json` via the SEMOSS reactor (see `MakePythonMCPReactor`) + +--- + +## Python MCP Tools + +### Tool Structure +```python +@mcp_metadata({ + 'loadingMessage': 'Processing...', + 'resourceURI': None, + 'execution': 'ask', # 'auto', 'ask', or 'disabled' + 'displayLocation': 'inline' # 'inline', 'sidebar', or 'hidden' +}) +def your_tool_name(param: str, model_id: str) -> str: + """ + Brief description of what the tool does. + + Args: + param: Description of parameter + model_id: The ID of the AI model to use + + Returns: + JSON string with results + """ + try: + # Your logic here + result = {'success': True, 'data': your_data} + return json.dumps(result) + except Exception as e: + import traceback + return json.dumps({ + 'success': False, + 'error': str(e), + 'traceback': traceback.format_exc() + }) +``` + +### Using Model Engines +Always require `model_id` as a parameter: + +```python +from ai_server import ModelEngine + +def your_tool(content: str, model_id: str) -> str: + model = ModelEngine(engine_id=model_id) + response = model.ask(command=prompt, param_dict={ + "temperature": 0.7, + "max_completion_tokens": 2000 + }) + # Parse and return response +``` + +### File Operations +Saving to insights folder: + +```python +from datetime import datetime +from pathlib import Path +import os + +# ROOT is injected by SEMOSS +file_path = os.path.join(Path(ROOT), filename) + +with open(file_path, 'w', encoding='utf-8') as f: + f.write(content) +``` + +--- + +## React UI Development + +### SDK Hooks +- **`useInsight()`**: Provides `actions`, `isReady`, `tool`, etc. +- **`useAppContext()`**: Custom context with `runPixel`, `sendMCPResponseToPlayground` + +```typescript +import { useInsight } from "@semoss/sdk/react"; +import { useAppContext } from "./contexts/AppContext"; + +const { actions, isReady } = useInsight(); // For MCP tools +const { runPixel } = useAppContext(); // For Pixel commands +``` + +### Model Selection Pattern +Fetching available models: + +```typescript +interface Engine { + app_id: string; + app_name: string; +} + +// Text generation models +const models = await runPixel( + `MyEngines( metaKeys = [], metaFilters = [{ "tag" : "text-generation" }], engineTypes = [ 'MODEL' ])` +); + +### Calling MCP Tools +```typescript +const { output } = await actions.runMCPTool("tool_name", { + param1: value1, + model_id: selectedModelId, +}); +``` + +### Response Parsing +MCP tool responses can be encoded multiple ways. Always handle all cases: + +```typescript +let data: YourResultType; + +if (typeof output === "string") { + try { + const parsed = JSON.parse(output); + // Check if double-encoded + if (typeof parsed === "string") { + data = JSON.parse(parsed) as YourResultType; + } else { + data = parsed as YourResultType; + } + } catch { + throw new Error("Failed to parse response"); + } +} else { + // Already an object + data = output as YourResultType; +} +``` + +--- + +## Common Gotchas + +### 1. Response Parsing +❌ **Wrong**: Assuming output is always a string +✅ **Right**: Handle object, string, and double-encoded cases + +### 2. MCP Metadata +❌ **Wrong**: Forgetting `@mcp_metadata` decorator +✅ **Right**: Every MCP tool must have `@mcp_metadata()` + +### 3. Parameter Passing +❌ **Wrong**: Using kwargs +✅ **Right**: Pass the parameter name and type - they will be interpretted as required parameters + +### 4. MCP Execution +- UI must target a specific tool name (from `mcp_driver.py`) +- Execute tools with `actions.runMCPTool(name, params)` +- Forward results with `actions.sendMCPResponseToPlayground` when needed + +--- + +## Best Practices + +### Python +- Use type hints for all parameters and return values +- Wrap MCP tool logic in try-catch blocks +- Return structured JSON from all MCP tools +- Keep MCP tool execution under 30 seconds +- Use streaming for long operations +- Cache expensive operations when appropriate + +### TypeScript +- Define interfaces for all data structures +- Handle all response encoding formats +- Validate user inputs before calling MCP tools +- Provide loading states during MCP execution +- Show meaningful error messages to users + +### Security +- Never expose API keys in frontend code +- Use environment variables for sensitive data +- Validate all user inputs in Python +- Sanitize HTML content before rendering + +### Testing Checklist +- [ ] Test with different models +- [ ] Test with empty/invalid inputs +- [ ] Test error handling +- [ ] Build without errors (`pnpm build`) +- [ ] Test in playground mode after publishing + +--- + +## File Pointers + +### Entry Points +- `portals/index.html` - Published app entry +- `client/src/index.tsx` - React entry point +- `client/src/App.tsx` - Main app component + +### MCP Tools +- `py/mcp_driver.py` - Python MCP tool definitions +- `mcp/py_mcp.json` - Generated Python manifest + +### Configuration +- `client/vite.config.ts` - Vite build config +- `client/tailwind.config.js` - Tailwind CSS config +- `biome.json` - Linting/formatting config + +### Generated +- Avoid direct edits to: `portals/`, `classes/`, `target/` + +--- + +## Do and Do Not + +### Do +- Keep UI in `client` +- Put custom logic in `py/mcp_driver.py` +- Build then publish via SEMOSS UI +- Use type hints in Python +- Handle all response encoding formats +- Validate inputs before processing + +### Do Not +- Edit built assets in `portals/` +- Manually edit `mcp/*.json` +- Commit secrets in `.env.local` +- Assume response format +- Skip error handling +- Forget `@mcp_metadata` decorator + +--- + +## Resources + +### Documentation +- [SEMOSS GitHub](https://github.com/SEMOSS/Semoss) (docs: https://github.com/SEMOSS/Semoss/tree/main/docs) +- [Monolith](https://github.com/SEMOSS/Monolith) +- [SEMOSS UI](https://github.com/SEMOSS/semoss-ui) + +### SDK +- `@semoss/sdk` and `@semoss/sdk/react` +- Python SDK: `ModelEngine`, `DatabaseEngine`, `Insight` from SEMOSS modules + +### Getting Help +When debugging: +1. Check browser console for frontend errors +2. Check SEMOSS logs for backend errors +3. Verify MCP manifest generated correctly +4. Test Python functions independently +5. Use network tab to inspect MCP tool responses \ No newline at end of file