Skip to content

Commit 99b5aee

Browse files
constantiniusconstantinius
committed
chore: add readme
1 parent 69e25ef commit 99b5aee

File tree

1 file changed

+236
-0
lines changed

1 file changed

+236
-0
lines changed

‎test-mcp/README.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# MCP Server Examples with Sentry Integration
2+
3+
This directory contains example [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers with Sentry integration, demonstrating three different API approaches: the standalone FastMCP library, the built-in MCP FastMCP module, and the low-level MCP API.
4+
5+
## 📚 About MCP
6+
7+
The [Model Context Protocol](https://github.com/modelcontextprotocol) is an open protocol that enables seamless integration between LLM applications and external data sources and tools.
8+
9+
## Examples
10+
11+
### 1. FastMCP Library Server (`main_fastmcp.py`)
12+
13+
Uses the standalone [`fastmcp`](https://github.com/jlowin/fastmcp) library - the most modern and feature-rich approach with HTTP support.
14+
15+
**Features:**
16+
- Decorator-based tool, resource, and prompt definitions
17+
- Automatic schema generation from type hints
18+
- Built-in HTTP server support with Starlette
19+
- Context injection support
20+
- Minimal boilerplate code
21+
22+
### 2. MCP Built-in FastMCP Server (`main.py`)
23+
24+
Uses `mcp.server.fastmcp.FastMCP` from the official MCP Python SDK - a simpler high-level API.
25+
26+
**Features:**
27+
- Decorator-based tool, resource, and prompt definitions
28+
- Automatic schema generation
29+
- Context injection support
30+
- STDIO transport only
31+
- Less boilerplate than low-level API
32+
33+
### 3. Low-Level Server (`main_lowlevel.py`)
34+
35+
Uses `mcp.server.lowlevel.Server` from the official MCP Python SDK - provides maximum control.
36+
37+
**Features:**
38+
- Manual schema definitions with full JSON Schema support
39+
- Explicit handler registration
40+
- Fine-grained control over protocol details
41+
- Direct access to MCP types
42+
- Best for complex custom behavior
43+
44+
## Common Features
45+
46+
All three examples demonstrate:
47+
48+
1. **Tools**: Functions that clients can call
49+
- `calculate_sum` - Add two numbers
50+
- `calculate_product` - Multiply two numbers
51+
- `greet_user` - Generate personalized greetings
52+
- `trigger_error` - Test Sentry error tracking
53+
54+
2. **Resources**: Data endpoints that clients can access
55+
- `config://settings` - Server configuration
56+
- `data://users` - User list
57+
- `data://stats` - Server statistics (low-level only)
58+
59+
3. **Prompts**: Reusable prompt templates
60+
- `code_review` - Code review template
61+
- `debug_assistant` - Debugging assistance template
62+
- `sql_query_helper` - SQL query help (low-level only)
63+
64+
## Running the Servers
65+
66+
### Prerequisites
67+
```bash
68+
# Install dependencies
69+
uv sync
70+
```
71+
72+
### FastMCP Library Server (HTTP)
73+
```bash
74+
# Using the script
75+
./run_fastmcp.sh
76+
77+
# Or directly
78+
uv run python main_fastmcp.py
79+
```
80+
81+
This starts an HTTP server on `http://127.0.0.1:8000` that you can interact with via HTTP requests.
82+
83+
### MCP Built-in FastMCP Server (STDIO)
84+
```bash
85+
# Using the script
86+
./run.sh
87+
88+
# Or directly
89+
uv run python main.py
90+
```
91+
92+
### Low-Level Server (STDIO)
93+
```bash
94+
# Using the script
95+
./run_lowlevel.sh
96+
97+
# Or directly
98+
uv run python main_lowlevel.py
99+
```
100+
101+
## Using with MCP Clients
102+
103+
The STDIO-based servers (`main.py` and `main_lowlevel.py`) can be used with any MCP-compatible client like [Claude Desktop](https://claude.ai/download).
104+
105+
### Example Client Configuration
106+
107+
For Claude Desktop, add to your configuration file:
108+
109+
**MCP Built-in FastMCP Server:**
110+
```json
111+
{
112+
"mcpServers": {
113+
"example-fastmcp": {
114+
"command": "uv",
115+
"args": ["run", "python", "/path/to/test-mcp/main.py"],
116+
"env": {
117+
"SENTRY_DSN": "your-sentry-dsn-here"
118+
}
119+
}
120+
}
121+
}
122+
```
123+
124+
**Low-Level Server:**
125+
```json
126+
{
127+
"mcpServers": {
128+
"example-lowlevel": {
129+
"command": "uv",
130+
"args": ["run", "python", "/path/to/test-mcp/main_lowlevel.py"],
131+
"env": {
132+
"SENTRY_DSN": "your-sentry-dsn-here"
133+
}
134+
}
135+
}
136+
}
137+
```
138+
139+
**FastMCP Library Server:**
140+
141+
The FastMCP Library server runs as an HTTP server and requires a different client setup that supports HTTP-based MCP connections. Alternatively, you can use it programmatically via HTTP requests.
142+
143+
## Testing with MCP Inspector
144+
145+
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a developer tool for testing and debugging MCP servers. It provides an interactive web interface to test your server's tools, resources, and prompts.
146+
147+
### Installation & Usage
148+
149+
The MCP Inspector can be run directly using `npx` without installation:
150+
151+
```bash
152+
npx @modelcontextprotocol/inspector
153+
```
154+
155+
### Testing Each Server Implementation
156+
157+
**MCP Built-in FastMCP Server (`main.py`):**
158+
```bash
159+
npx @modelcontextprotocol/inspector uv run python main.py
160+
```
161+
162+
**Low-Level Server (`main_lowlevel.py`):**
163+
```bash
164+
npx @modelcontextprotocol/inspector uv run python main_lowlevel.py
165+
```
166+
167+
**Note:** The FastMCP Library server (`main_fastmcp.py`) runs as an HTTP server and can be tested by navigating to `http://127.0.0.1:8000` in your browser after starting it.
168+
169+
### Using the Inspector
170+
171+
Once the inspector starts, it will:
172+
1. Open a web interface in your browser (typically at `http://localhost:5173`)
173+
2. Connect to your MCP server via STDIO
174+
3. Allow you to interactively test all tools, resources, and prompts
175+
4. Display request/response data for debugging
176+
177+
This is the recommended way to test and debug your MCP servers during development.
178+
179+
## Comparison: FastMCP Library vs MCP Built-in FastMCP vs Low-Level
180+
181+
| Feature | FastMCP Library | MCP Built-in FastMCP | Low-Level |
182+
|---------|-----------------|---------------------|-----------|
183+
| **Package** | `fastmcp` (standalone) | `mcp.server.fastmcp` | `mcp.server.lowlevel` |
184+
| **Code Style** | Decorator-based | Decorator-based | Handler registration |
185+
| **Boilerplate** | Minimal | Minimal | More verbose |
186+
| **Schema** | Auto-generated | Auto-generated | Manual JSON schema |
187+
| **Transport** | HTTP + STDIO | STDIO only | STDIO only |
188+
| **HTTP Support** | ✅ Built-in (Starlette) | ❌ | ❌ |
189+
| **Control** | Medium | Medium | Maximum |
190+
| **Best For** | Modern apps, HTTP APIs | Simple STDIO servers | Complex custom behavior |
191+
| **Learning Curve** | Easy | Easy | Steeper |
192+
193+
### When to Use FastMCP Library
194+
- Modern applications with HTTP support
195+
- Want to expose MCP server over the web
196+
- Need CORS, middleware, or HTTP-specific features
197+
- Prefer the most up-to-date FastMCP implementation
198+
199+
### When to Use MCP Built-in FastMCP
200+
- Simple STDIO-based servers
201+
- Want decorator-based API without external dependencies
202+
- Working with official MCP Python SDK
203+
- Traditional MCP server patterns
204+
205+
### When to Use Low-Level
206+
- Need fine-grained control over protocol
207+
- Custom protocol behavior or validation
208+
- Complex error handling requirements
209+
- Performance-critical applications
210+
211+
**See [COMPARISON.md](./COMPARISON.md) for detailed side-by-side code examples.**
212+
213+
## Sentry Integration
214+
215+
All three examples include Sentry integration using the `MCPIntegration()`. This provides:
216+
- Automatic error tracking for all MCP operations
217+
- Performance monitoring for tool calls
218+
- Breadcrumbs for debugging MCP interactions
219+
- Distributed tracing support
220+
221+
Configure Sentry by setting the `SENTRY_DSN` environment variable.
222+
223+
## Additional Resources
224+
225+
### MCP Documentation & Tools
226+
- [Model Context Protocol Official Site](https://modelcontextprotocol.io/)
227+
- [MCP GitHub Organization](https://github.com/modelcontextprotocol)
228+
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
229+
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - Test and debug MCP servers
230+
- [FastMCP Library](https://github.com/jlowin/fastmcp) - Standalone FastMCP with HTTP support
231+
- [MCP Specification](https://spec.modelcontextprotocol.io/)
232+
233+
### Client Applications
234+
- [Claude Desktop](https://claude.ai/download) - Official MCP client from Anthropic
235+
- [MCP Clients List](https://github.com/modelcontextprotocol/servers#clients) - Other MCP-compatible clients
236+

0 commit comments

Comments
 (0)