# my-mcp-tasks

An MCP (Model Context Protocol) learning project with two custom task manager servers and the prebuilt GitHub MCP server.

---

## Project structure

```
my-mcp-tasks/
├── reader_server.py     # MCP server: read tools (get_tasks, get_task_by_id)
├── writer_server.py     # MCP server: write tools (add_task, update_task)
├── mcp_config.json      # MCP server config for Claude
├── requirements.txt     # Python dependencies
├── tasks.db             # SQLite database (auto-created on first run)
├── .env                 # Your GitHub token (never commit this)
└── .gitignore
```

---

## Installation

### 1. Create and activate a virtual environment

```bash
python3 -m venv venv
source venv/bin/activate
```

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

---

## Setting up the GitHub MCP server

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate a new token with the scopes you need (e.g. `repo`, `read:user`)
3. Open `.env` and paste your token:

```
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
```

---

## Registering the servers with Claude

### Claude Desktop

1. Open Claude Desktop → Settings → Developer → Edit Config
2. Copy the contents of `mcp_config.json` into your Claude Desktop config
3. Replace `${workspaceFolder}` with the absolute path to this project folder
4. Replace `python3` with the full path to your venv Python, e.g.:
   `/Users/yourname/Desktop/Playground/MCP-Project/venv/bin/python`
5. Restart Claude Desktop

### Claude Code (CLI)

Run from inside this project folder with the venv active:

```bash
claude mcp add task-reader python3 reader_server.py
claude mcp add task-writer python3 writer_server.py
claude mcp add github npx -- -y @modelcontextprotocol/server-github
```

---

## Testing the custom task manager tools

Once the servers are registered, try these prompts in Claude:

**Add tasks**
> "Add a task called 'Buy groceries' with description 'Milk, eggs, bread'"
> "Create a task: title 'Fix login bug', description 'Users can't log in on mobile', status 'in-progress'"

**Read tasks**
> "Show me all my tasks"
> "Get task number 2"

**Update tasks**
> "Mark task 1 as done"
> "Update task 3's status to 'in-progress'"

---

## GitHub MCP server — what tools it adds

The prebuilt `@modelcontextprotocol/server-github` exposes tools for interacting with GitHub via Claude. You don't write any of this code — it runs via npx.

| Area | What you can do |
|---|---|
| Repositories | List your repos, get repo details, create a new repo |
| Files | Read file contents, list directory contents |
| Issues | Create issues, list issues, add comments |
| Pull requests | List PRs, get PR details, review PR diffs |
| Code search | Search across GitHub for code, files, or repos |

**Example prompts to try:**

> "List all my GitHub repositories"
> "Show me the contents of the README in my repo my-mcp-tasks"
> "Create a GitHub issue in my-mcp-tasks titled 'Add due date field to tasks'"
> "Search GitHub for MCP server examples in Python"

---

## How MCP works (the short version)

Each server runs as a separate process. Claude communicates with it over stdin/stdout. Claude sees only the tool **names and descriptions** — it uses those to decide which tool to call and with what arguments. Your handler code runs, queries the database (or calls the GitHub API), and returns a result that Claude reads and incorporates into its response.

In Python, FastMCP reads the **function name** as the tool name, the **docstring** as the description, and the **type hints** as the input schema — so there's no separate schema definition needed.