How arohitu/forceweaver-mcp-server works
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.