technical-notes-mcp

A Model Context Protocol server that lets Claude — or any MCP-compatible client — search your local notes directory and check live system resource usage. Built with TypeScript on the official @modelcontextprotocol/sdk, talking over stdio.

---

Demo

Architecture

The server is a Node process spoken to over stdio using JSON-RPC 2.0. Each MCP client (Inspector, Claude Desktop, Claude Code) spawns it as a subprocess and exchanges messages on its stdin/stdout. The server exposes two tools that read from the local filesystem and the Node os module.

Tools

search_technical_notes

Searches a local directory of markdown and code files for a keyword and returns the contents of the most relevant file.

Input	keyword (string) — the term to search for, case-insensitive
Output	Best-matching file's relative path, score, and full contents
Scoring	filename matches × 10, plus content occurrence count

Supported extensions: .md, .mdx, .txt, .ts, .tsx, .js, .jsx, .py, .go, .rs, .java, .c, .cpp, .h, .hpp, .rb, .sh, .json, .yaml, .yml. Files over 1 MB are skipped; node_modules, .git, dist, build, .venv, __pycache__, .cache, .next are pruned during the walk.

get_system_resource_usage

Returns a live snapshot of the host's CPU and memory.

Input	none
Output	platform, CPU%, memory used/free/total, uptime, ISO timestamp
Method	samples os.cpus() twice over 500 ms and computes busy-time delta

This is more accurate than os.loadavg() (which is Unix-only) and works on every platform Node supports.

---

Quick start

Requirements

• Node.js 18 or later
• An MCP client — the MCP Inspector for testing, or Claude Code for daily use

Install and build

git clone https://github.com/poplores/technical-notes-mcp.git
cd technical-notes-mcp
npm install
npm run build

The build produces build/index.js — the entry point an MCP client will spawn.

Configure your notes directory

The search tool reads from NOTES_DIR. Set this in your MCP client config (examples below) — never hardcode it in the source.

Verify it works

Run the official Inspector against the build:

NOTES_DIR=/path/to/your/notes npm run inspector

Windows (Command Prompt):

set NOTES_DIR=C:\path\to\your\notes
npm run inspector

Open the URL the Inspector prints, click Connect, then the Tools tab. Both tools should appear. Run search_technical_notes with a keyword you know is in your notes — it should return the matching file. Run get_system_resource_usage twice in a row — the timestamp and uptime should change, confirming live data.

---

Use it with an MCP client

Claude Code (recommended)

claude mcp add technical-notes \
  --env NOTES_DIR=/absolute/path/to/your/notes \
  -- node /absolute/path/to/technical-notes-mcp/build/index.js

Then in any Claude Code session: "Search my technical notes for X" or "What's my CPU usage?"

Claude Desktop

⚠️ The current MSIX/Microsoft Store builds of Claude Desktop on Windows have a known bug where they silently ignore mcpServers in claude_desktop_config.json. The macOS build is unaffected. If you're on Windows, use Claude Code for now.

On macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "technical-notes": {
      "command": "node",
      "args": ["/absolute/path/to/technical-notes-mcp/build/index.js"],
      "env": {
        "NOTES_DIR": "/absolute/path/to/your/notes"
      }
    }
  }
}

Restart Claude Desktop fully.

---

Project structure

technical-notes-mcp/
├── src/
│   └── index.ts            # Server setup + both tool handlers
├── docs/
│   ├── architecture.svg    # Diagram embedded above
│   └── demo.gif            # Demo embedded above
├── .github/workflows/
│   └── build.yml           # CI: typecheck + build on Node 18/20/22
├── package.json            # ESM, bin entry, build/inspector scripts
├── tsconfig.json           # ES2022 / Node16 module resolution
├── LICENSE                 # MIT
└── README.md

How it works (under the hood)

This is a stdio MCP server: a Node process that reads JSON-RPC requests on stdin and writes responses on stdout. Each MCP client spawns it as a subprocess; there's no network, no port, no shared state.

Don't console.log from a stdio MCP server. stdout is reserved for the protocol. The server uses console.error (stderr) for its startup message. Any stray write to stdout will break the JSON-RPC stream.

The get_system_resource_usage tool samples CPU counters twice over 500 ms and computes the busy-time delta across all cores — see the getCpuUsagePercent function in src/index.ts if you want to tune the sample window.

The search_technical_notes tool walks the directory with an async generator that yields one file path at a time, scoring each file with a simple weighted match count (filename_hits × 10 + content_hits). For a smarter scoring strategy, edit scoreFile — e.g. weight matches in markdown headers higher, or plug in a real tokenizer.

Extending it

• Different scoring — edit scoreFile in src/index.ts.
• More extensions — add to the ALLOWED_EXTENSIONS set.
• More tools — call server.registerTool(...) again with the same shape as the existing two. The SDK handles schema validation via Zod.

Troubleshooting

Symptom	Cause	Fix
Notes directory does not exist	NOTES_DIR not set or wrong path	Set it in the client config or env
Inspector "Disconnected" on connect	Build failed or path wrong	Re-run npm run build; check build/index.js exists
Tools don't appear in Claude Desktop on Windows	MSIX build ignores config	Use Claude Code instead
'chmod' is not recognized on Windows during build	Old build script	The current package.json uses just tsc

License

MIT — see LICENSE.