🧠 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):

{
  "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)

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

---

Running Manually

# 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

node server.js

Then paste (hit Enter after each line):

{"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

{
  "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.