Skip to main content
Glama
poplores

technical-notes-mcp

by poplores
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

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.

build Node License: MIT MCP

Demo

Inspector running both tools

Related MCP server: File Search Tool

Architecture

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

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.

Available Tools

2 tools
get_system_resource_usageGet System Resource UsageA

Return the current CPU usage percentage and memory usage (used / total / percent) of the host machine.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It states 'Return', which implies a read-only operation, effectively communicating non-destructive behavior. However, it does not explicitly confirm safety or mention any rate limits or authorization requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loads the purpose, and contains no wasted words. Every part adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description sufficiently explains what data is returned (CPU%, memory used/total/percent). It could optionally mention that values are real-time, but current is implied. The simplicity of the tool makes this complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4 per instructions. The schema coverage is 100% (no parameters to describe), and the description adds no parameter information, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and explicitly names the resources (CPU usage percentage, memory usage) with details on memory fields (used/total/percent). The name and description clearly distinguish it from the sibling tool 'search_technical_notes', which is unrelated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when current system resource metrics are needed, and the sibling tool's purpose (searching technical notes) is obviously different, so no explicit guidance is necessary. However, it lacks any when-not-to-use or prerequisite information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_technical_notesSearch Technical NotesA

Search local markdown and code files for a keyword and return the contents of the most relevant file. Searches the directory configured by the NOTES_DIR environment variable.

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYesThe keyword or phrase to search for (case-insensitive).

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that it searches markdown and code files and uses the NOTES_DIR environment variable. However, it does not explain what 'most relevant file' means, what happens on no match, or if multiple matches are possible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, no filler, and the first sentence immediately conveys the action. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description covers the scope, constraints (local files, env var), and output. It is mostly complete, though missing behavior on no match or multiple results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the 'keyword' parameter with case-insensitive behavior (100% coverage). The description adds no new parameter-level information beyond stating the file types (markdown and code), which is a minor addition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search local markdown and code files for a keyword') and the output ('return the contents of the most relevant file'). It distinguishes itself from the sibling tool 'get_system_resource_usage' which deals with system resources, making its purpose unique and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (when searching for a keyword in notes), but does not explicitly state when not to use it or mention alternatives. There is no guidance on prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.0.0
    • First observedget_system_resource_usage
    • First observedsearch_technical_notes
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation5/5

The two tools serve completely different purposes: one monitors system resources, the other searches technical notes. There is no risk of confusion.

Naming Consistency5/5

Both tool names follow the 'verb_noun' pattern in snake_case, which is consistent and clear.

Tool Count2/5

With only 2 tools, the server feels very thin. Moreover, the tools cover two unrelated domains (system monitoring and note searching), which is odd for a server named 'technical-notes-mcp'.

Completeness1/5

For a technical notes server, only a single search tool exists, lacking create, update, delete, or list operations. The system resource tool is out of place and does not address note management needs.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Notes Server

    truaxki
    A
    license
    B
    quality
    D
    maintenance
    An MCP server for managing and persisting notes, offering CRUD operations, note summarization, and resource-based access via a note:// URI scheme.
    4
    7
    MIT

  • File Search Tool

    RJTPP
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables file system search and inspection, including directory listing, regex-based file name and content searches, and reading text, PDF, and DOCX files.
    1
    MIT

  • emcp

    slezica
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server providing filesystem operations, shell execution, and web search capabilities.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/poplores/technical-notes-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server