# Enterprise MCP Server

Production-grade **FastMCP 3.x** server template built for teams that need to scale:
semantic tool retrieval, dynamic providers, parameterised resource templates,
paginated tool lists, session-scoped role unlocking, middleware, and full auth.

---

## Architecture

```
server.py               ← entry point — assembles everything
config/settings.py      ← ALL configuration  ← EDIT THIS FIRST
│
├── providers/          FastMCP 3.0 Dynamic Providers
│   └── registry.py     FileSystemProvider · OpenAPIProvider · ProxyProvider
│
├── transforms/         FastMCP 3.0 Transforms (middleware for providers)
│   └── pipeline.py     PrefixTransform · VersionFilter · TagFilter
│
├── tools/
│   ├── meta_tools.py   search_tools (Search Transform) · unlock_role (progressive disclosure)
│   └── example_tools.py  ← template for your own tools; drop files here
│
├── resources/
│   └── templates.py    Parameterised URIs: enterprise://tables/{name}/schema
│
├── middleware/
│   └── stack.py        Logging · RateLimiting · ResponseLimiting · Caching
│
├── auth/
│   └── setup.py        JWT · OAuth 2.1 · Bearer
│
└── utils/
    ├── lifespan.py     Startup / shutdown hooks
    └── otel.py         OpenTelemetry tracing
```

---

## FastMCP 3.x Scale Features Used

| Feature | Where | Config key |
|---|---|---|
| **Pagination** (`list_page_size`) | `server.py` | `LIST_PAGE_SIZE` |
| **Dynamic Providers** | `providers/registry.py` | `PROVIDERS` |
| **Search Transforms** (meta-tool) | `tools/meta_tools.py` | `SEMANTIC_SEARCH` |
| **Resource Templates** | `resources/templates.py` | `RESOURCE_TEMPLATES` |
| **Session State** + progressive disclosure | `tools/meta_tools.py` | `ROLE_GATES` |
| **Component Versioning** | `tools/example_tools.py` | `VERSIONING` |
| **Tag-based visibility** | `transforms/pipeline.py` | `ROLE_GATES` |
| **Background Tasks** | `tools/example_tools.py` | `BACKGROUND_TASKS` |
| **Returnable errors** | `tools/example_tools.py` | — |
| **OpenTelemetry** | `utils/otel.py` | `OTEL` |

---

## Quickstart

```bash
# 1. Install
pip install fastmcp>=3.4.1 httpx

# 2. Configure
#    Open config/settings.py and fill every  <CONFIGURE>  marker.

# 3. Run (development — hot reload)
fastmcp dev server.py

# 4. Run (production)
python server.py
```

### Optional extras

```bash
pip install fastmcp[tasks]   # background tasks via Docket
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http  # OTEL
```

---

## How to Add Your Own Tools

Drop a `.py` file into `tools/` with a local `mcp = FastMCP(...)` instance and
decorate your functions.  `FileSystemProvider` picks them up automatically
(set `PROVIDERS.filesystem.reload = True` for zero-restart hot-reload).

```python
# tools/my_api_tools.py
from fastmcp import FastMCP, Context

mcp = FastMCP("my-api")

@mcp.tool(tags={"data", "read"}, version="1.0")
async def get_report(report_id: str, ctx: Context) -> dict:
    """Fetch an enterprise report by ID."""
    # ... your implementation
    return {}
```

Sensitive tools?  Add `tags={"admin"}` (or any key in `ROLE_GATES`) and they
are hidden from the default tool list.  Clients call `unlock_role("admin")`
after authenticating to reveal them for their session.

---

## Semantic Search Flow

```
LLM calls search_tools(query="show me revenue by region")
         │
         ▼
   Your retrieval API  (SEMANTIC_SEARCH.api_base_url)
         │
         ▼
   Top-K tools above score_threshold returned to LLM
         │
         ▼
   LLM calls the specific tool it needs
```

The LLM never receives the full tool catalog — only the relevant subset.

---

## Pagination Flow

```
Client sends  tools/list  (no cursor)
         │
         ▼
   Server returns  page 1  (LIST_PAGE_SIZE items) + nextCursor
         │
         ▼
   Client sends  tools/list?cursor=<nextCursor>
         │
         ▼
   ... repeat until nextCursor is null
```

`fastmcp.Client.list_tools()` handles this automatically.
Use `list_tools_mcp(cursor=...)` for manual control.

---

## Testing

```bash
pip install pytest pytest-asyncio
pytest tests/
```