# arohitu/forceweaver-mcp-server architecture

> Architecture diagram of the GitHub repository arohitu/forceweaver-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arohitu/forceweaver-mcp-server
- Repository: https://github.com/arohitu/forceweaver-mcp-server

## Overview

##### Project type and purpose
- This is an open-source Python “MCP” server package (forceweaver-mcp-server) that implements the standard MCP (Multi-Channel Protocol) interface over STDIO and HTTP.
- It exposes a set of health-checking tools for Salesforce Revenue Cloud, allowing AI agents (VS Code Copilot, Claude, Cline, etc.) to invoke commands like `revenue_cloud_health_check`, `get_detailed_bundle_analysis`, etc.
- It acts as a proxy/adapter between AI clients and the ForceWeaver backend API (mcp.forceweaver.com), enforcing security best practices, authentication, and input validation.

##### File structure
- Top-level:
– packaging & config: `pyproject.toml`, `requirements.txt`, `MANIFEST.in`
– CI: `.github/workflows/ci.yml`
– docs & governance: `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `LICENSE`
– examples: JSON configs for VS Code, Claude, Cursor
– tests: `tests/test_server.py`
- Core module: `forceweaver_mcp_server/`
– `__main__.py`: entry point for `python -m forceweaver_mcp_server`
– `server.py`: starts the MCP server, registers handlers for each tool
– `exceptions.py`: domain-specific errors and validation
- No frontend code: this is purely a backend/service component.

##### Extract architectural insights from README
- Dual transport support (stdio & HTTP) configurable via JSON or environment variables.
- Uses environment variables for API URL, API key, Salesforce Org ID.
- Complies with MCP security best practices: token validation, input sanitization, TLS.
- Integrates with external ForceWeaver Dashboard and Salesforce Org.

a. Main components
- AI Agents (Clients) – e.g., VS Code Copilot Chat, Claude Desktop, Cline, other MCP-compliant clients
- Transport Layer – STDIO connector and HTTP server
- MCP Server Core –
– Entry point (`__main__.py`)
– Command Dispatcher & handlers (`server.py`)
– Error & Security module (`exceptions.py`)
- ForceWeaver Backend API – public HTTPS endpoint (mcp.forceweaver.com)
- Salesforce Org – the target system under test
- Dev/CI Environment – GitHub Actions, tests, packaging pipeline
b. Relationships & interactions
1. AI Agent → (STDIO or HTTP) → MCP Server
2. MCP Server authenticates request, loads env/config, dispatches to tool handler
3. Handler calls ForceWeaver Backend API (HTTPS) with API key & Org ID
4. Backend service queries Salesforce Org, performs health checks, returns JSON
5. MCP Server formats response, writes back via STDIO/HTTP to AI client
6. Tests & CI validate the server logic upon each PR
c. Architectural patterns & principles
- Adapter/Facade pattern: abstracts HTTP/stdio transport
- Single-process CLI server, pluggable “tools” for each health-check command
- Separation of concerns: transport vs. command logic vs. external API integration
- Security layer ensures token validation, input sanitization, TLS enforcement
d. Key technologies & libraries
- Python 3.x, pip packaging (pyproject.toml, MANIFEST.in)
- Standard library: argparse or MCP protocol client libraries
- HTTP client (requests or httpx) for backend calls
- GitHub Actions (`ci.yml`) for CI and coverage reports
- JSON config for VS Code/Claude (`examples/*.json`)

##### Diagramming recommendations
- Use clear, concise labels: “AI Agent (VS Code, Claude)”, “MCP StdIO Connector”, “MCP HTTP Server”, “Command Dispatcher”, “ForceWeaver API”, “Salesforce Org”.
– Blue for internal components (server modules)
– Green for external clients/services
– Orange for CI/Dev tooling
– Rectangles for services/processes
– Clouds for external APIs/services

##### Detail and granularity
- Every major module in `forceweaver_mcp_server/`.
- Environment variables and config files feeding into the transport layer.
- Security checks in the data flow between client and server, and server and backend.
- Do not over-simplify: separate the two transports, the dispatcher, and the external API client.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        AI["AI Agent (VS Code, Claude, Cline)"]:::external
    end

    %% MCP Server Core
    subgraph "MCP Server Core"
        EP["Entry Point (__main__.py)"]:::internal
        Transport["Transport Layer"]:::internal
        subgraph "Transport Layer"
            STDIO["MCP StdIO Connector"]:::internal
            HTTP["MCP HTTP Server"]:::internal
        end
        Dispatcher["Command Dispatcher (server.py)"]:::internal
        APIClient["ForceWeaver API Client"]:::internal
        Exceptions["Error & Security Module"]:::internal
    end

    %% External Services
    subgraph "External Services"
        FWAPI["ForceWeaver Backend API (mcp.forceweaver.com)"]:::external
        Salesforce["Salesforce Org"]:::external
    end

    %% Dev/CI Environment
    subgraph "Dev/CI Environment"
        ci["GitHub Actions CI Pipeline"]:::dev
        tests["Automated Tests (tests/test_server.py)"]:::dev
        subgraph "Packaging & Config"
            pyproject["pyproject.toml"]:::dev
            requirements["requirements.txt"]:::dev
            manifest["MANIFEST.in"]:::dev
        end
        subgraph "Example Client Configs"
            vscode["vscode-mcp-config.json"]:::dev
            claude["claude-desktop-config.json"]:::dev
            devcfg["development-mcp-config.json"]:::dev
        end
        subgraph "Docs & Governance"
            readme["README.md"]:::dev
            contributing["CONTRIBUTING.md"]:::dev
            codeofconduct["CODE_OF_CONDUCT.md"]:::dev
            license["LICENSE"]:::dev
            changelog["CHANGELOG.md"]:::dev
        end
        subgraph "Editor/IDE Helpers"
            vscode_dir[".vscode/"]:::dev
            cursor[".cursor/mcp.json"]:::dev
        end
    end

    %% Configuration
    Config["Env Vars & JSON Config"]:::internal

    %% Connections
    AI -->|via STDIO or HTTP| STDIO
    AI -->|via STDIO or HTTP| HTTP
    STDIO -->|dispatch| Dispatcher
    HTTP -->|dispatch| Dispatcher
    Dispatcher -->|"validate & sanitize"| Exceptions
    Dispatcher -->|invoke| APIClient
    APIClient -->|HTTPS requests| FWAPI
    FWAPI -->|queries| Salesforce
    APIClient -->|response| Dispatcher
    Dispatcher -->|response| STDIO
    Dispatcher -->|response| HTTP

    Config -->|env/config| STDIO
    Config -->|env/config| HTTP

    ci -.->|runs| tests
    ci -.->|runs| pyproject
    ci -.->|runs| requirements
    ci -.->|runs| manifest
    tests -->|validates| Dispatcher

    %% Click Events
    click EP "https://github.com/arohitu/forceweaver-mcp-server/blob/main/forceweaver_mcp_server/__main__.py"
    click Dispatcher "https://github.com/arohitu/forceweaver-mcp-server/blob/main/forceweaver_mcp_server/server.py"
    click Exceptions "https://github.com/arohitu/forceweaver-mcp-server/blob/main/forceweaver_mcp_server/exceptions.py"
    click pyproject "https://github.com/arohitu/forceweaver-mcp-server/blob/main/pyproject.toml"
    click requirements "https://github.com/arohitu/forceweaver-mcp-server/blob/main/requirements.txt"
    click manifest "https://github.com/arohitu/forceweaver-mcp-server/blob/main/MANIFEST.in"
    click ci "https://github.com/arohitu/forceweaver-mcp-server/blob/main/.github/workflows/ci.yml"
    click tests "https://github.com/arohitu/forceweaver-mcp-server/blob/main/tests/test_server.py"
    click vscode "https://github.com/arohitu/forceweaver-mcp-server/blob/main/examples/vscode-mcp-config.json"
    click claude "https://github.com/arohitu/forceweaver-mcp-server/blob/main/examples/claude-desktop-config.json"
    click devcfg "https://github.com/arohitu/forceweaver-mcp-server/blob/main/examples/development-mcp-config.json"
    click readme "https://github.com/arohitu/forceweaver-mcp-server/blob/main/README.md"
    click contributing "https://github.com/arohitu/forceweaver-mcp-server/blob/main/CONTRIBUTING.md"
    click codeofconduct "https://github.com/arohitu/forceweaver-mcp-server/blob/main/CODE_OF_CONDUCT.md"
    click license "https://github.com/arohitu/forceweaver-mcp-server/tree/main/LICENSE"
    click changelog "https://github.com/arohitu/forceweaver-mcp-server/blob/main/CHANGELOG.md"
    click vscode_dir "https://github.com/arohitu/forceweaver-mcp-server/tree/main/.vscode/"
    click cursor "https://github.com/arohitu/forceweaver-mcp-server/blob/main/.cursor/mcp.json"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef dev fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
```
