docs(examples): add multi-server + agent integration guides#3
Merged
Conversation
- Fix mcp-forge-core README: github.com/mcp-forge/mcp-forge (404) → github.com/CoreNovus/mcp-forge - Fix Quick Start example: mcp.run() → run_server(mcp) to use the mode-switching server factory - Remove PLAN.md: documented Protocol-based architecture but code uses ABCs, template filenames and workflow structure were outdated Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Scaffold (mcp-forge-cli):
- Use SandboxedEnvironment instead of Environment to prevent Jinja2
template introspection attacks via custom --templates directories
- Add path traversal guard in MCPServerScaffold.generate() — verify
output stays within the intended parent directory
- Add validate_text_field() to reject unsafe characters (", \n, \r, \)
in author/email/description fields before template interpolation
- Call validation in orchestrator before scaffolding
Providers (mcp-forge-core):
- InMemoryCache: add max_size parameter with oldest-first eviction to
prevent unbounded memory growth in long-running dev servers
- InMemoryTelemetry: add max_metrics parameter with rolling window
- Default server_host from 0.0.0.0 to 127.0.0.1 in config.py and
server_factory.py to prevent unintended network exposure in dev
AWS providers (mcp-forge-aws):
- Narrow exception handling: catch (ClientError, BotoCoreError) instead
of bare Exception in DynamoDB and CloudWatch providers — let
programming errors propagate instead of being silently swallowed
- CloudWatch: use asyncio.to_thread() for consistency with DynamoDB
providers instead of loop.run_in_executor(lambda)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- bedrock_llm.py: remove no-op message conversion loop — the ternary and subsequent for-loop were both identity operations - retry.py: extract _execute_with_retry() to eliminate duplicated retry loop between @Retry decorator and with_retry() function; log type(exc).__name__ instead of full exception message to avoid leaking sensitive data in retry warnings - cli.py: fix version command — use proper __version__ import instead of hacky ScaffoldConfig.__module__.split('.')[0] - test_scaffold.py: add encoding="utf-8" to all read_text() calls — fixes 2 pre-existing test failures on Windows cp950 locale caused by em-dash characters in generated server.py docstring Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Make the mcp SDK an invisible implementation detail of mcp-forge-core so that generated servers never import from mcp.server.fastmcp directly. - Re-export FastMCP from mcp_forge_core.__init__ — users can now write from mcp_forge_core import FastMCP for type annotations - Update test_sample.py.j2 to use create_mcp_app() instead of directly importing FastMCP from the mcp SDK - Remove redundant mcp>=1.0 dependency from pyproject.toml.j2 — it is already a transitive dependency via mcp-forge-core When mcp SDK 2.0 ships, only server_factory.py needs updating — no generated user code will break. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds examples/README.md as the scenario picker and examples/multi-server/ with a step-by-step walkthrough, docker-compose.yml for three scaffolded servers on 8001/8002/8003, a shared Dockerfile, and an .env.example for the common MCP_* knobs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Introduces examples/agent-integration/ with the transport-choice explainer (http vs stdio), shared prerequisites, and a pointer to the two framework sub-folders that follow in subsequent commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pseudo-code agent.py showing how to open an MCP ClientSession against each of the three servers, flatten tool manifests into Anthropic tool_use format with server-prefixed names, and run an agentic loop with tool routing. Includes README with step-by-step usage and a requirements.txt pinning the minimal deps. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pseudo-code agent.py using langchain-mcp-adapters' MultiServerMCPClient to aggregate tools from the three servers into a LangGraph prebuilt ReAct agent. Includes README explaining when to pick this over the raw Anthropic SDK approach and a requirements.txt with the LangChain stack. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
examples/with two scenarios so users can quickly bootstrap a multi-MCP architecture:multi-server/— scaffold 3 servers viamcp-forge new, orchestrate withdocker-compose.yml, env template, shared Dockerfile, full walkthrough READMEagent-integration/— transport-choice guide (HTTP vs stdio) plus two framework blueprints:anthropic-sdk/— explicit agentic loop withanthropicSDK +mcpclient (server-prefixed tool routing)langchain-langgraph/—MultiServerMCPClient+ prebuiltcreate_react_agentDocs-only change. No framework code touched. Agent-side
agent.pyfiles are clearly marked pseudo-code because the MCP client / LangChain-MCP adapter APIs are still in flux.Split across 4 topical commits for reviewability:
db0270emulti-server scenario + top-level indexb169af0agent-integration overview62b5a1dAnthropic SDK blueprint3f8fdceLangChain/LangGraph blueprintTest plan
examples/README.mdrenders on GitHub and inter-doc links resolvemcp-forge new search-mcp -o examples/multi-serverscaffolds cleanlydocker-compose up --buildinexamples/multi-server/brings up ports 8001/8002/8003 once the three packages are scaffoldedagent.pyis prominent enough