# Teaching MCP Server

A small, local **Model Context Protocol (MCP)** server built for teaching
purposes. It demonstrates five of the most common categories of things MCP
servers are used for, with heavily commented, readable TypeScript source.

## The five capabilities

| # | Capability | Tools |
|---|---|---|
| 1 | Local filesystem access | `read_file`, `write_file`, `list_directory` |
| 2 | Persistent structured storage (CRUD) | `add_note`, `list_notes`, `get_note`, `delete_note` |
| 3 | Outbound HTTP / calling external APIs | `fetch_url` |
| 4 | Local system introspection | `get_system_info` |
| 5 | Deterministic text processing | `analyze_text`, `transform_text` |

See `FUNCTIONAL_SPEC.md` for what each tool does and why, `TECHNICAL_SPEC.md`
for how it's built, and `HOW_IT_WORKS.md` for a guided walkthrough of MCP
itself using this project as the example.

## Quick start

```bash
npm install
npm run build
npm start
```

The server speaks MCP over **stdio**, so running `npm start` directly in a
terminal will just sit there waiting for a client to talk to it — that's
expected. It's meant to be launched by an MCP client such as Claude Code or
Claude Desktop.

### Connect it to Claude Code

Add it as a local MCP server (from this project directory):

```bash
claude mcp add teaching-mcp-server -- node dist/index.js
```

### Connect it to Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "teaching-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/claude-mcp-2/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop, then look for the tools icon to confirm the server
connected and its 11 tools are listed.

## Project layout

```
claude-mcp-2/
├── src/
│   ├── index.ts            # Entry point: creates the server, registers tools, connects stdio
│   ├── paths.ts             # Filesystem sandboxing helper (workspace path validation)
│   ├── notesStore.ts        # JSON-file-backed persistence for the notes tools
│   └── tools/
│       ├── filesystem.ts    # Capability 1
│       ├── notes.ts         # Capability 2
│       ├── web.ts           # Capability 3
│       ├── system.ts        # Capability 4
│       └── text.ts          # Capability 5
├── workspace/                # Sandbox root for read_file / write_file / list_directory
├── data/                     # notes.json lives here
├── HOW_IT_WORKS.md
├── FUNCTIONAL_SPEC.md
└── TECHNICAL_SPEC.md
```

## Try it

Once connected in Claude Code or Claude Desktop, try asking:

- "List the files in your workspace, then read welcome.txt."
- "Add a note titled 'Groceries' with a short shopping list, then show me all my notes."
- "Fetch https://example.com and summarize what's there."
- "What's the CPU and memory usage on this machine?"
- "Count the words and get a SHA-256 hash of this paragraph: ..."