# MCP Server Boilerplate

A minimal, extensible template for building Python-based MCP (Model-Context Protocol) servers.
This repository provides a small, well-documented starting point that demonstrates common
patterns for transport selection, tool registration, configuration, and VS Code integration.

## Overview

This boilerplate implements:
- A simple MCP server entrypoint (`mcp_server.py`)
- Pluggable transports (STDIO and SSE) selectable via `mcp_settings.py`
- A transport configurator that can generate a `.vscode/mcp.json` entry
- A clear place to add MCP tools (commands) and helper modules

The goal is to make it easy to prototype and ship MCP servers that integrate with tooling
and editors while keeping the code small and approachable.

## Features

- Example STDIO and SSE transports with configuration
- Automated VS Code server configuration (`mcp_transport_configurator.py`)
- Virtual-environment friendly startup and `PYTHONPATH` support
- Lightweight structure for adding MCP tools and utilities

## File Structure

```
├── mcp_server.py
├── mcp_settings.py
├── mcp_setup_env.py
├── mcp_transport_configurator.py
├── mcp_utils.py
├── requirements.txt
├── README.md
└── tools/               # place to add reusable helper modules
```

Customize the layout as your project grows — add `src/`, `tests/`, or split tools into packages.

## Setup

1. Create and activate a virtual environment (recommended):
   ```bash
   python -m venv .venv
   # Windows
   .venv\Scripts\activate
   # macOS/Linux
   source .venv/bin/activate
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. (Optional) Run the environment helper to set a project env var used by the configurator:
   ```bash
   python mcp_setup_env.py
   ```

## Configuration

Edit `mcp_settings.py` to choose transport protocol and other runtime options:

- `PROTOCOL` — set to `STDIO` (default) or `SSE`
- `PORT` — used only for SSE mode
- `MCP_NAME` — logical name used by the transport configurator

## Running the Server

Start the server directly:
```bash
python mcp_server.py
```

Or only update the editor/server configuration without starting:
```bash
python mcp_transport_configurator.py
```

## VS Code Integration

The included configurator writes a `.vscode/mcp.json` entry that can be used by editor
extensions to launch the MCP server in STDIO mode or connect via SSE.

## Development Notes

- Prefer keeping `requirements.txt` or migrate to `pyproject.toml` + lockfile for modern dependency management.
- Add unit tests under `tests/` and run them with your preferred test runner.
- Keep tools small and focused; register MCP commands from a single initialization point.

## Contributing

Contributions are welcome. Open issues or pull requests for bug fixes, documentation improvements,
or new example tools demonstrating MCP patterns.

## License

See the `LICENSE` file for licensing details.

## Author

Provided as an MCP server boilerplate.