initial mcp server setup

2025-09-11 23:13:58 +01:00
commit 20f96c0f30
141 changed files with 14444 additions and 0 deletions
@@ -0,0 +1,97 @@
+# MCP Development Setup
+
+This document explains how to use the MCP development server with different transport methods.
+
+## Quick Start with MCP Dev Command
+
+The easiest way to run the MCP server in development mode is using the dedicated dev file:
+
+```bash
+mcp dev dev_run.py
+```
+
+This will:
+- ✅ Automatically start the server with SSE transport
+- ✅ Run on port 3000 (standard dev port)
+- ✅ Show the server URL: `http://0.0.0.0:3000/sse`
+- ✅ Auto-discover and register tools, prompts, and resources
+
+## Alternative Development Methods
+
+### Using the Main Server Script
+
+```bash
+# Development mode (SSE on port 3000)
+python run_mcp_server.py --dev
+
+# Custom development setup
+python run_mcp_server.py --transport sse --port 8080
+```
+
+### Manual Server Control
+
+```bash
+# Default stdio transport
+python run_mcp_server.py
+
+# SSE transport
+python run_mcp_server.py --transport sse
+
+# Custom port
+python run_mcp_server.py --transport sse --port 8080
+
+# Streamable HTTP
+python run_mcp_server.py --transport streamable-http --port 9000
+```
+
+## Transport Methods
+
+### 1. STDIO Transport (Default)
+- **Use case**: Command-line tools, testing
+- **Port**: Not applicable (uses stdio)
+- **Command**: `python run_mcp_server.py --transport stdio`
+
+### 2. SSE Transport
+- **Use case**: Web applications, development
+- **Default port**: 8050 (3000 in dev mode)
+- **Command**: `python run_mcp_server.py --transport sse --port 8080`
+
+### 3. Streamable HTTP Transport
+- **Use case**: Production HTTP applications
+- **Default port**: 8050
+- **Command**: `python run_mcp_server.py --transport streamable-http --port 9000`
+
+## MCP Dev Command Usage
+
+The `dev_run.py` file is optimized for the MCP dev command:
+
+1. **Automatic Discovery**: MCP dev finds the server object automatically
+2. **Standard Port**: Uses port 3000 (industry standard for dev)
+3. **SSE Transport**: Optimized for web development
+4. **Clean Output**: Shows clear status messages and URLs
+
+## Server Features
+
+The MCP server automatically:
+- 🔍 Discovers tools from `src/mcp_template/tools/`
+- 📝 Discovers prompts from `src/mcp_template/server/prompts/`
+- 📁 Discovers resources from `src/mcp_template/server/resources/`
+- 🚀 Registers all components with the MCP server
+- 🌐 Provides appropriate transport endpoints
+
+## Troubleshooting
+
+### MCP Dev Command Issues
+- Make sure `dev_run.py` is in the project root
+- Ensure the MCP CLI is properly installed
+- Check that the `mcp` object is properly exposed
+
+### Port Conflicts
+- Change ports using `--port` parameter
+- Common dev ports: 3000, 8080, 9000
+- Check for running processes: `lsof -i :PORT`
+
+### Import Errors
+- Ensure you're running from the project root
+- Check that all dependencies are installed
+- Verify Python path includes the `src` directory