# MCP Server Starter

[![CI](https://github.com/Quartalis/mcp-server-starter/actions/workflows/ci.yml/badge.svg)](https://github.com/Quartalis/mcp-server-starter/actions/workflows/ci.yml)

A minimal **MCP (Model Context Protocol)** server with 2 working tools, ready to use with Claude Desktop and Claude Code.

Built and maintained by [Darren Betney](https://github.com/Quartalis).

---

## What's Included

- Calculator tool
- Memory (key-value store) tool
- Claude Desktop config
- Claude Code integration
- Automated tests

---

## Quick Start

### 1. Clone the repo

```bash
git clone https://github.com/Quartalis/mcp-server-starter.git
cd mcp-server-starter
```

### 2. Run the tests

```bash
pip install pytest
python -m pytest -v tests
```

`tests/test_tools.py` covers the two tool implementations; `tests/test_protocol.py` covers the JSON-RPC layer (`initialize`, `tools/list`, `tools/call`, error codes, `Content-Length` framing). The same suite runs in GitHub Actions on Python 3.10, 3.11 and 3.12 on every push and pull request (`.github/workflows/ci.yml`).

### 3. Configure Claude Desktop

Copy the snippet from `claude_desktop_config.json` into your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Update the `cwd` path to point to your cloned directory.

### 4. Configure Claude Code

Add to your `.claude/settings.json`:

```json
{
  "mcpServers": {
    "mcp-server-starter": {
      "command": "python",
      "args": ["src/server.py"],
      "cwd": "/path/to/mcp-server-starter"
    }
  }
}
```

### 5. Restart Claude and use the tools

Ask Claude to:
- "Calculate 2 ** 10 + 15 * 3"
- "Store my project name as 'My App' in memory"
- "List everything in memory"

---

## Tools

### Calculator

Evaluates mathematical expressions safely. Supports `+`, `-`, `*`, `/`, `**`, and parentheses.

```
Input:  {"expression": "(2 + 3) * 4"}
Output: "(2 + 3) * 4 = 20"
```

### Memory Store

A session-scoped key-value store. Data persists for the duration of the server process.

| Action | Description |
|--------|-------------|
| `set` | Store a key-value pair |
| `get` | Retrieve a value by key |
| `list` | Show all stored keys |
| `delete` | Remove a key |

```
Input:  {"action": "set", "key": "project", "value": "My SaaS"}
Output: "Stored: project = My SaaS"
```

---

## Project Structure

```
mcp-server-starter/
├── .github/
│   └── workflows/
│       └── ci.yml         # GitHub Actions: pytest on Python 3.10–3.12
├── src/
│   ├── __init__.py
│   └── server.py          # MCP server with tool handlers
├── tests/
│   ├── test_tools.py      # Unit tests for both tools
│   └── test_protocol.py   # JSON-RPC handshake, tools/list, tools/call, framing
├── claude_desktop_config.json
├── pyproject.toml
└── LICENSE
```

---

## Requirements

- Python 3.10+
- No external dependencies (stdlib only)

---

## How MCP Works

The Model Context Protocol allows AI assistants like Claude to call tools hosted on your machine. The server communicates over stdin/stdout using JSON-RPC, following the [MCP specification](https://modelcontextprotocol.io).

This starter implements the core protocol:
- `initialize` / `notifications/initialized` handshake
- `tools/list` to advertise available tools
- `tools/call` to execute a tool and return results

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

## Links

- [MCP Specification](https://modelcontextprotocol.io) — Official protocol docs