Metadata-Version: 2.4
Name: forge-os-mcp
Version: 0.2.0
Summary: MCP Meta-Orchestrator for Forge — routes, secures, budgets, and caches tool calls across N upstream MCP servers.
Project-URL: Homepage, https://github.com/angelnicolasc/forge
Project-URL: Repository, https://github.com/angelnicolasc/forge
Project-URL: Issues, https://github.com/angelnicolasc/forge/issues
Project-URL: Changelog, https://github.com/angelnicolasc/forge/blob/main/CHANGELOG.md
Author-email: Angel DiCerutti <angelnicolascorzo@gmail.com>
License-Expression: Apache-2.0
Keywords: agents,forge,mcp,model-context-protocol,routing,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0
Requires-Dist: forge-os-core==0.2.0
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog<26.0,>=24.0
Provides-Extra: sdk
Requires-Dist: mcp>=1.0; extra == 'sdk'
Description-Content-Type: text/markdown

# forge-mcp

MCP Meta-Orchestrator for Forge — routes, secures, budgets, and caches tool calls across N upstream MCP servers.

## Features

- **Deny-by-default security**: tools must be explicitly `allowed: true` per server config
- **Caller allowlists**: restrict tool access to specific agent/caller IDs
- **Secret redaction**: responses are scanned and sanitized before reaching the agent context
- **Per-run budgets**: configurable `max_calls_per_run` per tool; `BudgetExceededError` on breach
- **Exact-match TTL cache**: Anthropic prompt-caching semantics — identical input → cache hit
- **Circuit breakers**: per-server, reusing `forge-core.CircuitBreaker` (5 failures → OPEN)
- **YAML config**: human-friendly server and policy authoring
- **CLI**: `forge mcp list-tools`, `forge mcp call`, `forge mcp status`

## Quick start

```python
from forge_mcp import MetaMCPServer, ServerConfig, ToolCall, ToolPolicy, FakeMCPClient

server = MetaMCPServer()
cfg = ServerConfig(
    name="filesystem",
    transport="stdio",
    command=["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    tools={"read_file": ToolPolicy(allowed=True, max_calls_per_run=20)},
)
server.add_server(cfg, FakeMCPClient(responses={"read_file": "file contents"}))

result = await server.call_tool(ToolCall(tool_name="read_file", arguments={"path": "/tmp/x.txt"}))
print(result.content)
```

## YAML config

```yaml
cache_ttl: 300
servers:
  - name: filesystem
    transport: stdio
    command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    tools:
      read_file:
        allowed: true
        max_calls_per_run: 20
      write_file:
        allowed: true
        max_calls_per_run: 5
```

## Part of Forge

This package is part of [Forge](https://github.com/angelnicolasc/forge) — the universal AI agent harness.
