# 🧠 Knowledge Base MCP Server

A **zero-dependency** Model Context Protocol (MCP) server that gives Claude
a persistent personal knowledge base — built entirely with Node.js built-ins.

---

## What is MCP?

The **Model Context Protocol** is an open standard (by Anthropic) that lets AI
assistants talk to external tools and data sources in a structured, secure way.
Think of it as a universal plugin system for LLMs.

```
┌─────────────────┐         JSON-RPC 2.0        ┌──────────────────────┐
│  Claude Desktop  │  ◄────── stdio ──────────►  │  knowledge-mcp       │
│  (MCP host)      │                             │  (this server)       │
└─────────────────┘                             └──────────────────────┘
         │                                                │
         │  calls tools like kb_search(query="python")   │
         │  reads resources like kb://notes              │
         └────────────────────────────────────────────────┘
```

Every message is a JSON-RPC 2.0 object sent over **stdin/stdout**.

---

## Architecture

```
server.js
├── Persistence layer     loadDB / saveDB  (JSON file in ~/)
├── Business logic        noteAdd / noteSearch / noteList / noteDelete / noteStats
├── MCP dispatch table    dispatch(method, params, db)  →  result | error
└── stdio transport       readline loop  →  JSON-RPC framing
```

### The MCP Handshake

```
client → server:  initialize   { protocolVersion, clientInfo }
server → client:  result       { protocolVersion, capabilities, serverInfo }
client → server:  notifications/initialized   (no response expected)
```

After this, the client can call any method at any time.

---

## Tools

| Tool | Description |
|------|-------------|
| `kb_add` | Store a note with title, content, and optional tags |
| `kb_search` | Full-text + tag search (AND logic for multiple tags) |
| `kb_list` | List all notes, optionally filtered by tag |
| `kb_delete` | Delete a note by ID |
| `kb_stats` | Summary stats: note count, tag index, newest/oldest |

## Resources

| URI | Description |
|-----|-------------|
| `kb://notes` | Complete JSON dump of all notes |
| `kb://tags` | Tag → note-list index |

---

## Installation

### Prerequisites
- Node.js 18+ (no npm packages required)

### Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/knowledge-mcp/server.js"]
    }
  }
}
```

Restart Claude Desktop. You'll see a 🔌 icon confirming the server connected.

### Add to Claude Code (CLI)

```bash
claude mcp add knowledge-base node /absolute/path/to/server.js
```

---

## Running Manually

```bash
# Start the server (stays alive, reads from stdin)
node server.js

# Run unit tests
node server.js --test

# Run integration tests (spawns a real server subprocess)
node integration-test.js
```

### Try it interactively

```bash
node server.js
```
Then paste (hit Enter after each line):
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"kb_add","arguments":{"title":"Hello","content":"My first note","tags":["demo"]}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"kb_search","arguments":{"query":"first"}}}
```

---

## Key Design Decisions

1. **Zero dependencies** — Ships as a single file. Works wherever Node ≥ 18 exists.
2. **File persistence** — Notes survive restarts. DB lives at `~/.knowledge-mcp-db.json`.
3. **Strict JSON-RPC** — Correct error codes (-32601 method-not-found, -32603 internal,
   -32700 parse-error) so MCP hosts can handle errors gracefully.
4. **Notifications handled** — `notifications/initialized` is a one-way message;
   the server silently ignores it rather than sending a bogus response.
5. **isError flag** — Tool errors use `{ isError: true }` per spec, not JSON-RPC errors,
   so Claude sees the error text rather than a protocol failure.

---

## Data Format

```json
{
  "id": "1",
  "title": "MCP Guide",
  "content": "Model Context Protocol connects AI to tools.",
  "tags": ["mcp", "ai"],
  "createdAt": "2026-03-09T05:00:00.000Z",
  "updatedAt": "2026-03-09T05:00:00.000Z"
}
```

---

## Extending This Server

To add a new tool:

1. Add its logic as a plain function (e.g. `noteUpdate`)
2. Add a descriptor object to the `TOOLS` array
3. Add a `case 'kb_update':` to the `tools/call` switch block

That's it — no framework, no codegen, no magic.