Content
# MCP Server Cookie Cutter Template
A cookie cutter template for creating new MCP (Model Context Protocol) servers. This template generates a fully functional MCP server with multi-transport support (stdio, SSE, and streamable HTTP), advanced logging, automatic decorators, and a web-based management UI.
## Features
- **Multi-Transport Support**: stdio, SSE, and streamable HTTP in a single implementation
- **Automatic Decorators**: Exception handling, logging, type conversion, and parallelization
- **Unified Logging System**: SQLite-based logging with correlation IDs and extensible destinations
- **Web Management UI**: Streamlit-based interface for configuration, logs, and documentation
- **Example Tools**: Ready-to-use example tools with best practices
- **Full MCP Inspector Compatibility**: Easy testing and debugging
- **Proper Absolute Imports**: Clean package structure throughout
- **DevFlow Integration**: Built-in JIRA workflow commands (plan-work, implement, security-review, complete)
- **Comprehensive Documentation**: Templates for README, development guide, and setup prompts
## Prerequisites
1. Python 3.11 or higher
```bash
python --version # Should be 3.11 or higher
```
2. uv (Fast Python package installer)
```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
```
3. Cookie Cutter
```bash
uv pip install cookiecutter
```
## Creating a New MCP Server
You can create a new MCP server either directly from GitHub or from a local copy of this template.
### Option 1: Directly from GitHub
```bash
cookiecutter gh:codingthefuturewithai/mcp-cookie-cutter
```
### Option 2: From Local Copy
1. Clone this template:
```bash
git clone https://github.com/codingthefuturewithai/mcp-cookie-cutter
```
2. Create a project using the local template:
```bash
cookiecutter path/to/mcp-cookie-cutter
```
### Template Configuration
You'll be asked for:
- `project_name`: Human-readable name (e.g., "My MCP Server")
- `__project_slug`: Python package name (auto-generated from project_name, e.g., "my_mcp_server")
- `description`: Short description of your project
- `author_name`: Your name
- `email`: Your email address
- `server_port`: Port for SSE and HTTP transports (default: 3001)
## Generated Project Structure
```
my_mcp_server/ # Your project directory
├── .claude/ # Claude Code integration
│ ├── agents/ # Security scanner agent
│ └── commands/ # DevFlow workflow commands
│ └── devflow/ # JIRA-integrated development workflow
├── my_mcp_server/ # Python package directory
│ ├── __init__.py
│ ├── __main__.py
│ ├── client/ # Client implementations
│ │ ├── __init__.py
│ │ └── app.py # Test client for development
│ ├── server/ # Server implementation
│ │ ├── __init__.py
│ │ └── app.py # Multi-transport MCP server (stdio, SSE, HTTP)
│ ├── tools/ # Tool implementations
│ │ ├── __init__.py
│ │ └── example_tools.py # Example tools with decorators
│ ├── decorators/ # Automatic tool decorators
│ │ ├── exception_handler.py
│ │ ├── tool_logger.py
│ │ ├── type_converter.py
│ │ └── parallelize.py
│ ├── log_system/ # Unified logging system
│ │ ├── correlation.py # Correlation ID tracking
│ │ ├── unified_logger.py # Main logging interface
│ │ └── destinations/ # Log destinations (SQLite, etc.)
│ ├── ui/ # Streamlit management UI
│ │ ├── app.py
│ │ ├── lib/ # UI components and utilities
│ │ └── pages/ # UI pages (Home, Config, Logs, Docs)
│ ├── config.py # Server configuration
│ └── logging_config.py # Logging setup
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── pyproject.toml # Project configuration and dependencies
├── README.md # Project documentation template
├── DEVELOPMENT.md # Development guide
├── DEVELOPER_GUIDE.md # Developer reference
└── SETUP_PROMPT.md # AI-assisted setup guide
```
## Next Steps
Once your project is generated:
1. **Review Documentation Templates**
- Customize `README.md` for your project
- Review `DEVELOPMENT.md` for development workflow
- Check `DEVELOPER_GUIDE.md` for architectural details
- Use `SETUP_PROMPT.md` for AI-assisted setup
2. **Set Up Development Environment**
- Install dependencies: `uv pip install -e .`
- Run tests: `pytest`
- Start the server: `python -m your_project_name --transport stdio`
3. **Explore Transports**
- **STDIO**: `python -m your_project_name --transport stdio`
- **SSE**: `python -m your_project_name --transport sse --port 3001`
- **Streamable HTTP**: `python -m your_project_name --transport streamable-http --port 3001`
4. **Test with MCP Inspector**
- Install: `npm install -g @modelcontextprotocol/inspector`
- Run: `mcp dev your_project_name/server/app.py`
5. **Access Management UI**
- Start UI: `streamlit run your_project_name/ui/app.py`
- View logs, configure server, browse documentation
6. **Add Your Own Tools**
- Add functions to `tools/example_tools.py`
- Decorators are applied automatically
- Register in `example_tools` or `parallel_example_tools` lists
7. **Use DevFlow Workflow** (Optional)
- Connect to JIRA
- Use `/devflow:plan-work ISSUE-KEY` to plan
- Use `/devflow:implement ISSUE-KEY` to implement
- Use `/devflow:security-review ISSUE-KEY` to scan
- Use `/devflow:complete ISSUE-KEY` to create PR
## License
This template is licensed under the MIT License - see the LICENSE file for details.
