mcp -boilerplate

MCP Base is a Python-based starting point for building MCP servers. It provides a modular foundation with base classes for tools, prompts, and resources, plus multiple transport layers (STDIO, SSE, HTTP) to connect with LLMs and agentic clients. The repository ships with example structure and registries so you can rapidly extend functionality by adding new tools, prompts, and resources and registering them in the appropriate registries. Use the STDIO transport for local development and CLI-style integration, or explore SSE/HTTP transports for web-based or streaming interactions with clients.

To run the server, use the STDIO transport by default: python main.py --transport=stdio. This will boot the server and expose the tool/prompt/resource interfaces via the standard input/output channel. For other transports, consult the README sections under src/transports/stdio, src/transports/sse, and src/transports/http for transport-specific setup details, configuration, and usage. As you add new features, create a class in the corresponding module (e.g., src/tools/ for tools, src/prompts/ for prompts, src/resources/ for resources), implement the required interfaces, and register the new feature in its registry so it becomes available to clients through the MCP layer.

This boilerplate is designed to be extended. You can configure environment-driven settings, plug in custom validators with Pydantic schemas, and adjust security and sandboxing policies as you add tools and resources. The result is a production-ready, maintainable server that can be deployed via Docker or directly on Python environments.

Prerequisites:

• Python 3.8+ with pip
• Git (optional, for cloning)

1. Create and activate a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

2. Install dependencies from requirements.txt (or pyproject.toml if provided):

pip install -r requirements.txt

3. (Optional) Install as editable package if you plan to develop against it:

pip install -e .

4. Run the server (STDIO transport by default):

python main.py --transport=stdio

5. If you plan to run HTTP or SSE transports, review src/transports/README.md files for transport-specific dependencies and start-up steps. You may need to install extra packages or provide configuration values via a .env file (copy .env.example to .env and fill in required values).

6. Docker (optional):

• Build: docker build -t mcp-base:latest .
• Run: docker run -i mcp-base:latest

Ensure environment variables and any required credentials are provided in your environment or via a .env file when running in containers.

Tips and common considerations:

• Use the provided registries to add your own tools, prompts, and resources; keep domain logic isolated and well-documented.
• Leverage environment variables for sensitive configuration (e.g., API keys, secrets) and avoid hard-coding credentials.
• Review the transport README files under src/transports/ for integration details and examples specific to STDIO, SSE, and HTTP transports.
• Run tests with Pytest as indicated in the project guidelines and contribute to the tests directory to maintain reliability.
• If you encounter sandboxing or path permission issues, double-check the allowed paths in file operations and verify environment permission settings.