How bitteprotocol/mcp works
<explanation>
To create a precise system design diagram for this MCP Proxy Monorepo, follow these tailored steps:
1. Identify the project type and purpose
- This is a backend‑focused monorepo hosting one or more MCP (Model Control Protocol) servers.
- The primary service (“bitte‑ai”) delivers real‑time SSE (Server‑Sent Events) streams at the /sse endpoint, allowing clients (e.g., the Cursor app) to connect and receive model control data.
2. Analyze the file structure
- Top‑level directories and files:
• apps/bitte‑ai: contains the MCP server implementation (config.ts, index.ts, plugins, tools, utils).
• packages/: placeholder for additional MCP servers or shared libraries.
• scripts/: orchestration scripts (docker‑down, start‑all, start‑dev).
• docker-compose.yml: local container orchestration.
• .github/workflows/cicd.yml: CI/CD pipeline on GitHub Actions.
• turbo.json & tsconfig.json: Turborepo monorepo settings.
• biome.json: code quality configuration.
- Key patterns:
• Monorepo management via Turborepo.
• Containerization with Docker + Docker Compose.
• SSE as the communication mechanism with external clients.
3. Examine the README for additional insights
- Confirms Bun as the runtime.
- Defines commands for build, dev, lint, starting services.
- Points to externally hosted SSE URI (https://mcp.bitte.ai/sse).
- Describes how to add additional MCP servers under packages/.
4. Main components and their interactions
a. Developer Workstation
• Tools: Bun runtime, Turborepo, Biome, Docker CLI.
• Executes bun run dev / scripts/start-dev.ts to run local services.
b. Monorepo Build Layer
• Turborepo gathers code from apps/ and packages/, compiles via Bun/tsup, outputs artifacts.
• Biome ensures code quality.
c. CI/CD Pipeline (GitHub Actions)
• Triggers on pushes/PRs.
• Runs build, tests, lint, and Docker image publishing.
d. Container Layer (Docker Compose)
• Hosts one or more MCP server containers (bitte‑ai).
• Configurations injected via .env or .env.example.
e. MCP Server (bitte‑ai)
• HTTP server exposing /sse SSE endpoint.
• Internally uses plugins (lib/bitte-plugins.ts), search utilities, and tools (base‑agentkit, goat‑sdk).
• Connects to downstream AI/Model services or registries via utils/bitte.ts and utils/search.ts.
f. External Clients
• Cursor app or other consumers subscribes to the SSE stream at https://mcp.bitte.ai/sse.
5. Architectural patterns and design principles
- Monorepo with isolated workspaces for each service.
- Modular code: clear separation into config, core logic (index.ts), plugins, utilities, SDK wrappers.
- Containerization for environment parity.
- CI/CD as code for automated quality gates and deployments.
- SSE for uni‑directional, real‑time event streaming.
6. Diagramming guidelines
- Use containers or swimlanes for each layer: Developer, CI/CD, Build, Containerized Runtime, External Clients.
- Represent each MCP service as a separate box inside the Containerized Runtime layer.
- Show arrows:
• Developer → Build (Turborepo)
• Build → CI/CD → Docker Registry
• Docker Registry → Container Orchestrator (Docker Compose)
• Container → External Client (SSE stream)
• MCP Server ↔ Plugin Modules / SDK Tools
- Color‑code:
• Green for developer/build tools
• Blue for runtime services
• Orange for external clients
• Grey for infrastructure (CI/CD, Docker)
- Label each component clearly: include names (bitte‑ai, base-agentkit, goat-sdk), file paths, and protocols (HTTP, SSE).
7. Tailoring to this monorepo
- Emphasize that each new MCP server in packages/ follows the same pattern: config, entrypoint, plugins, and utils.
- Show extensibility by adding a “New MCP Service” box linked to the Build and Container layers.
- Highlight Turborepo and Bun as the underlying monorepo and runtime foundation.
By following these steps and including all key layers, components, data flows, and color‑coded distinctions, you’ll produce an accurate, detailed system design diagram that captures the essential architecture of the MCP Proxy Monorepo.