{
  "markdown": "[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/rogermt/forgesyte)\n# ForgeSyte\n\nForgeSyte is a modular AI‑vision MCP server engineered for developers who demand precision, extensibility, and absolute clarity in their tooling. Built in Python using the `uv` toolchain and designed for seamless integration with Gemini‑CLI, ForgeSyte acts as a vision analysis core capable of loading, executing, and orchestrating pluggable vision modules.\n\nAt its heart, ForgeSyte is a forge: a place where perception is shaped, refined, and extended. Every module—OCR, object detection, mapping, classification, or custom logic—slots into a unified contract, enabling reproducible, auditable, and future‑proof workflows.\n\nWhether you're building automated analysis pipelines, real‑time camera tools, or domain‑specific vision systems, ForgeSyte provides the foundation: a stable schema, a clean API surface, and a plugin architecture engineered for growth.\n\n---\n\n## Features\n\n- **Modular Vision Engine**  \n  Drop‑in Python plugins that implement a simple, explicit contract.\n\n- **MCP‑Native**  \n  Exposes tools and capabilities directly to Gemini‑CLI via a clean MCP manifest.\n\n- **Python‑First Architecture (uv‑powered)**  \n  FastAPI core, plugin loader, and analysis pipeline built for clarity and extensibility.\n\n- **Optional React UI**  \n  A lightweight React/TypeScript interface for live camera streaming, job monitoring, and plugin management.\n\n- **Deterministic & Auditable**  \n  Every module declares its inputs, outputs, and metadata.\n\n---\n\n## Repository Structure\n\n```text\nforgesyte/\n├─ server/\n│  ├─ app/\n│  │  ├─ main.py\n│  │  ├─ api.py\n│  │  ├─ mcp_adapter.py\n│  │  ├─ plugin_loader.py\n│  │  ├─ plugins/\n│  │  │  └─ __init__.py\n│  │  ├─ models.py\n│  │  └─ tasks.py\n│  ├─ pyproject.toml\n│  └─ uv.lock\n├─ example_plugins/\n│  ├─ ocr_plugin/\n│  └─ block_mapper/\n├─ web-ui/\n│  ├─ src/\n│  ├─ public/\n│  └─ package.json\n├─ gemini_extension.json\n├─ PLUGIN_DEVELOPMENT.md\n├─ CONTRIBUTING.md\n└─ README.md\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.10+  \n- **uv** (https://github.com/astral-sh/uv)  \n- Node.js 18+ (for React UI)  \n- Optional: Docker\n\n---\n\n## Backend Setup (uv)\n\n```bash\ncd server\nuv sync\nuv run fastapi dev app/main.py\n```\n\nForgeSyte will start at:\n\n- API: `http://localhost:8000`\n- Docs: `http://localhost:8000/docs`\n- MCP manifest: `http://localhost:8000/v1/mcp-manifest`\n\n---\n\n## Frontend Setup (React)\n\n```bash\ncd web-ui\nnpm install\nnpm run dev\n```\n\nRuns at:\n\n```\nhttp://localhost:5173\n```\n\n---\n\n## Using ForgeSyte with Gemini‑CLI\n\nForgeSyte integrates with Gemini‑CLI as an MCP server. There are two steps:\n\n---\n\n### 1. Install ForgeSyte as a Gemini‑CLI extension\n\n```bash\n# Install directly from GitHub\ngemini extensions install https://github.com/rogermt/forgesyte\n\n# Or install from a local checkout\ngemini extensions install /path/to/forgesyte\n```\n\n---\n\n### 2. Add ForgeSyte to Gemini‑CLI MCP configuration\n\nEdit your Gemini‑CLI user config (e.g., `~/.gemini-cli/settings.json`):\n\n```json\n{  \n  \"$schema\": \"https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json\",  \n  \"mcpServers\": {  \n    \"forgesyte\": {  \n      \"httpUrl\": \"http://localhost:8000\",  \n      \"timeout\": 30000,  \n      \"description\": \"ForgeSyte AI-vision MCP server\"  \n    }  \n  }  \n}\n```\n\nRestart Gemini‑CLI, then verify:\n\n```bash\ngemini-cli tools list\n```\n\nYou should see tools such as:\n\n- `vision.ocr`\n- `vision.block_mapper`\n\n---\n\n## Execution Governance\n\nForgeSyte's execution layer is governed by strict mechanical rules enforced via a static scanner and CI pipeline.\n\n### Quick Links\n\n- **Execution Governance Documentation:** [`docs/design/execution-governance.md`](docs/design/execution-governance.md)\n  - Architecture overview\n  - Plugin lifecycle states\n  - Job lifecycle\n  - Validation rules\n  - Error envelope format\n  - Scanner rules\n  - CI enforcement\n\n- **Architecture Diagrams:** [`docs/design/execution-architecture.drawio`](docs/design/execution-architecture.drawio)\n  - Visual execution flow\n  - Component dependencies\n  - Job lifecycle diagram\n  - Registry state machine\n  - Error envelope flow\n\n- **Developer Onboarding:** [`docs/design/execution-onboarding.md`](docs/design/execution-onboarding.md)\n  - Core mental model\n  - Running tests\n  - Running the scanner\n  - Adding plugins\n  - Adding execution features\n  - Debugging execution issues\n\n- **Phase 12 Wrap‑Up:** [`docs/phase12-wrap-up.md`](docs/phase12-wrap-up.md)\n  - What Phase 12 achieved\n  - Key guarantees enforced\n  - Future enhancements\n\n- **Repository Audit Checklist:** [`docs/repo-audit-checklist.md`](docs/repo-audit-checklist.md)\n  - Verify governance compliance\n  - Check directory structure\n  - Validate architecture\n  - Ensure CI enforcement\n\n### Running the Mechanical Scanner\n\nThe scanner enforces execution governance invariants:\n\n```bash\npython scripts/scan_execution_violations.py\n```\n\nIf it prints `✅ PASSED`, you're compliant. If it prints violations, fix them before committing.\n\nCI runs this automatically on every PR and push to `main`.\n\n---\n\n## Architecture Overview\n\nSee `ARCHITECTURE.md` for the full diagram.\n\n---\n\n## Troubleshooting MCP Discovery\n\n### ForgeSyte not appearing in `gemini-cli tools list`\n\n- Ensure the server is running:\n\n  ```bash\n  curl http://localhost:8000/v1/mcp-manifest\n  ```\n\n- Check your Gemini config for typos in:\n\n  - `mcpServers`\n  - `forgesyte`\n  - `httpUrl`\n\n- Restart Gemini‑CLI after editing settings.\n\n### Manifest returns 500\n\n- A plugin likely has invalid metadata.\n- Check ForgeSyte logs for `ValidationError`.\n\n### Tool invocation returns 404\n\n- Plugin name in `?plugin=` may not match the plugin folder name.\n- Ensure plugin is loaded by `plugin_loader.py`.\n\n---\n\n## Contributing\n\nSee `CONTRIBUTING.md`.\n\n---\n\n## Plugin Development\n\nSee `PLUGIN_DEVELOPMENT.md`.\n\n---\n\n## Contract Tests (JSON-Safe Output Validation)\n\nForgeSyte enforces that all plugin tools return JSON-serializable output. This prevents numpy arrays, tensors, or custom objects from leaking into API responses.\n\n### Running Contract Tests\n\n**CPU (CI environment):**\n```bash\ncd server\nuv run pytest tests/contract/ -v\n```\n\n**GPU (Kaggle with YOLO models):**\n```bash\ncd server\nRUN_MODEL_TESTS=1 uv run pytest tests/contract/ -v\n```\n\n### What Contract Tests Verify\n\n- **All plugins loaded** via `entry_points(group=\"forgesyte.plugins\")`\n- **All tools callable** via `plugin.run_tool(tool_name, args)`\n- **All outputs JSON-safe** — can be serialized via `json.dumps()`\n- **No numpy/torch leaks** — arrays and tensors rejected\n\nSee `server/tests/contract/` for implementation details.\n\n---\n\n## Scope Guardrails\n\nThe following features are **explicitly out of scope** for ForgeSyte and must not be implemented:\n\n- No export  \n- No record button  \n- No model selector  \n- No WebSocket selector  \n\nAny PR adding these features will be rejected.\n\nSee `docs/design/video-tool-runner.md` for the canonical Video Tool Runner UI specification.\n\n---\n\n## Branding\n\nSee `BRANDING.md`.\n\n---\n\n## License\n\nTBD.\n```\n\n---\n\n# ✅ 2. **Gemini‑CLI Quickstart Mini‑Guide**\n\n```md\n# ForgeSyte + Gemini‑CLI Quickstart\n\nThis guide shows the fastest way to use ForgeSyte as an MCP server inside Gemini‑CLI.\n\n---\n\n## 1. Start ForgeSyte\n\n```bash\ncd forgesyte/server\nuv sync\nuv run fastapi dev app/main.py\n```\n\n---\n\n## 2. Install ForgeSyte as a Gemini extension\n\n```bash\ngemini extensions install https://github.com/rogermt/forgesyte\n```\n\n---\n\n## 3. Add ForgeSyte to Gemini MCP config\n\nEdit your Gemini settings file:\n\n```json\n{\n  \"mcpServers\": {\n    \"forgesyte\": {\n      \"httpUrl\": \"http://localhost:8000\",\n      \"type\": \"http\"\n    }\n  }\n}\n```\n\n---\n\n## 4. Verify tools are available\n\n```bash\ngemini-cli tools list\n```\n\nYou should see:\n\n- `vision.ocr`\n- `vision.block_mapper`\n\n---\n\n## 5. Use ForgeSyte inside Gemini\n\nExamples:\n\n- “Use ForgeSyte OCR on this screenshot.”\n- “Analyze this image with the block mapper.”\n```\n\n---\n\n# ✅ 3. **Troubleshooting Block (MCP Discovery Issues)**\n\n```md\n# MCP Discovery Troubleshooting\n\n### ForgeSyte does not appear in `gemini-cli tools list`\n\n- Ensure ForgeSyte is running:\n\n  ```bash\n  curl http://localhost:8000/v1/mcp-manifest\n  ```\n\n- Check Gemini config for typos:\n\n  - `mcpServers`\n  - `forgesyte`\n  - `httpUrl`\n\n- Restart Gemini‑CLI after editing settings.\n\n---\n\n### Manifest returns 500\n\n- A plugin likely has invalid metadata.\n- Check ForgeSyte logs for:\n\n  - `ValidationError`\n  - Missing fields in `metadata()`\n  - Incorrect types\n\n---\n\n### Tools appear but invocation fails\n\n- Ensure plugin name matches:\n\n  ```\n  /v1/analyze?plugin=<name>\n  ```\n\n- Confirm plugin folder name matches plugin `name` field.\n\n---\n\n### Gemini‑CLI says “server unreachable”\n\n- Check port:\n\n  ```bash\n  curl http://localhost:8000/\n  ```\n\n- Ensure no firewall is blocking localhost.\n```\n\n---\n\n# ✅ 4. **Correct `gemini_extension.json`**\n\nThis is the correct filename and structure for Gemini extensions.\n\n```json\n{\n  \"name\": \"ForgeSyte\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Modular AI-vision MCP server exposing pluggable vision tools.\",\n  \"homepage\": \"https://github.com/rogermt/forgesyte\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/rogermt/forgesyte.git\"\n  },\n  \"license\": \"MIT\",\n  \"categories\": [\n    \"vision\",\n    \"analysis\",\n    \"developer-tools\"\n  ],\n  \"author\": {\n    \"name\": \"ForgeSyte\",\n    \"url\": \"https://github.com/rogermt\"\n  },\n  \"mcpServers\": {\n    \"forgesyte\": {\n      \"httpUrl\": \"http://localhost:8000\",\n      \"type\": \"http\"\n    }\n  }\n}\n```\n",
  "bytes": 9542,
  "sha": "dfa0674661377d54d5b623afed2451480170de20a273b67dbe268f566e27277c",
  "repo_slug": "rogermt/forgesyte",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_rogermt_forgesyte_0f46e745/readme"
}