When we open-sourced okf-wiki-mcp — a small MIT-licensed stdio Model Context Protocol (MCP) server for querying local Markdown and OKF v0.2 meeting-note vaults — getting initialize and tools/call working locally on a laptop took one afternoon.
Getting that same server to pass automated registry validators across npm, the Official MCP Registry, Docker's MCP Registry (cmd/validate), and Glama's inspection pipeline (from 33% discovery score with unrated tool quality to 100% and TDQS A · 4.5/5.0) exposed four subtle engineering edge cases that rarely show up in toy MCP examples.
Here is every failure we hit and the exact code that fixed it.
1. Dual Stdio Framing Without Pulling In an SDK Tree
One explicit goal for okf-wiki-mcp was zero third-party runtime dependencies (node:fs and node:path only) so users can inspect every line before mounting a private folder of notes into Claude Desktop, Claude Code, or Cursor.
In practice, MCP clients and test harnesses are not consistent about stdio framing:
- Some hosts and LSP-derived wrappers send
Content-Length: <bytes>\r\n\r\n<json>. - Newer MCP clients and CLI probes send newline-delimited JSON-RPC (
<json>\n).
If your server hardcodes one format, half the ecosystem hangs waiting for EOF or headers. The fix is a 35-line adaptive buffer loop that inspects the first 32 bytes of incoming data and mirrors whichever framing style the caller used:
export function startStdioMcpServer( vaultDir, input = process.stdin, output = process.stdout, ) { let buffer = Buffer.alloc(0); let useContentLength = false; function send(resp) { if (!resp) return; const json = JSON.stringify(resp); if (useContentLength) { output.write( `Content-Length: ${Buffer.byteLength(json, 'utf8')}\r\n\r\n${json}`, ); } else { output.write(`${json}\n`); } } input.on('data', (chunk) => { buffer = Buffer.concat([ buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk), ]); while (buffer.length > 0) { if (/^Content-Length:/i.test(buffer.slice(0, 32).toString('utf8'))) { useContentLength = true; const sepIdx = buffer.indexOf('\r\n\r\n'); if (sepIdx === -1) break; const m = buffer .slice(0, sepIdx) .toString('utf8') .match(/Content-Length:\s*(\d+)/i); if (!m) { buffer = buffer.slice(sepIdx + 4); continue; } const len = Number(m[1]); const bodyStart = sepIdx + 4; if (buffer.length < bodyStart + len) break; const jsonStr = buffer .slice(bodyStart, bodyStart + len) .toString('utf8'); buffer = buffer.slice(bodyStart + len); try { send(handleMcpRequest(vaultDir, JSON.parse(jsonStr))); } catch {} } else { const nlIdx = buffer.indexOf('\n'); if (nlIdx === -1) break; const line = buffer.slice(0, nlIdx).toString('utf8').trim(); buffer = buffer.slice(nlIdx + 1); if (!line) continue; try { send(handleMcpRequest(vaultDir, JSON.parse(line))); } catch {} } } }); } Two small details that prevented subtle bugs in automated inspection:
- Always measure
Buffer.byteLength(json, 'utf8'), neverjson.length, when writingContent-Lengthheaders—multi-byte UTF-8 notes (German, French, Korean, emoji) will otherwise truncate the frame. - Silently ignore JSON-RPC notifications (
id === undefined || id === null, such asnotifications/initialized) instead of emitting an error response onstdout.
2. The Zero-Config Container Trap (VOLUME + isRequired: true)
When automated MCP directories (like Glama's hosted build/inspection runner) evaluate your server, they build your Dockerfile and boot the container without mounting any user directory and without setting custom environment variables, then run initialize and tools/list.
Our first v1.0.1 image failed inspection for two reasons:
- Our
DockerfiledeclaredVOLUME ["/vault"]without creating/vaultahead of time. - Our
server.jsonmarkedOKF_VAULT_DIRas"isRequired": true.
Switching to an explicit directory + safe empty-vault default fixed container inspection immediately (Build success in ~22s):
FROM node:22-alpine WORKDIR /app COPY package.json server.json glama.json LICENSE README.md SKILL.md ./ COPY bin ./bin COPY src ./src RUN mkdir -p /vault ENV NODE_ENV=production ENV OKF_VAULT_DIR=/vault ENTRYPOINT ["node", "/app/bin/okf-wiki-mcp.mjs", "--serve"] And in server.json (using the Official MCP Registry 2025-12-11 schema):
{ "environmentVariables": [ { "name": "OKF_VAULT_DIR", "description": "Optional path to your local OKF v0.2 or Obsidian Markdown meeting-notes directory (defaults to /vault in Docker or current working directory).", "isRequired": false, "isSecret": false } ] } On the application side, walkMarkdownFiles() returns [] if the vault directory is empty or missing, so okf_vault_stats returns clean zeros rather than crashing on startup, and read-only container mounts (-v ~/notes:/vault:ro with disableNetwork: true) work identically in air-gapped environments.
3. Turning Unrated Tool Schemas Into TDQS A (4.5/5.0)
Early on, our tools/list response looked like a lot of minimal MCP servers:
- Tool names + a one-line
description - Bare parameter types (
{ query: { type: "string" } }) with no parameter descriptions, defaults, or bounds - No
title, noadditionalProperties: false, and no MCPannotations
When an LLM client loads 15–30 tools across multiple MCP servers, sparse schemas cause two real failures: models call okf_read_note for fuzzy keyword queries (instead of okf_search_meetings), or guess invalid enum values / unbounded limits.
Upgrading all 5 tools with four concrete additions raised our automated Tool Definition Quality Score to A · 4.5/5.0 (5/5 tools rated A) and Server Coherence Disambiguation to 5/5:
- Human-readable
title+ MCP behavioralannotations:-
readOnlyHint: true,destructiveHint: false,idempotentHint: true,openWorldHint: false.
-
- Explicit cross-tool disambiguation inside
description:- Tell the model when to use this tool AND which sibling tool to prefer instead, plus what the empty/error return shape looks like.
- Strict parameter contracts:
-
additionalProperties: false, concretedescriptionwith example inputs, explicitdefault,enum,minLength,minimum, andmaximum.
-
- Structured error returns for expected misses:
- When
okf_read_notecannot find a slug, return{ isError: true, content: [{ type: 'text', text: 'Note not found: ...' }] }instead of throwing an unhandled JSON-RPC-32603internal error.
- When
Here is the real schema we shipped in v1.0.3 for okf_list_action_items:
{ name: 'okf_list_action_items', title: 'List Meeting Action Items', description: 'Extract Markdown task checklist items (- [ ] open or - [x] completed) and @owner / bold-owner assignments across all local meeting notes in the vault. ' + 'Use this for follow-up tracking, standups, and accountability reviews; prefer okf_search_meetings for general topic search or okf_read_note for full meeting context around a task. ' + 'Read-only and 100% offline. Returns a JSON array of action item objects containing file, line, completed, owner, text, title, and date, or [] when none match.', annotations: { title: 'List Meeting Action Items', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, inputSchema: { type: 'object', additionalProperties: false, properties: { status: { type: 'string', enum: ['open', 'completed', 'all'], description: 'Filter checklist items by completion state: "open" for unchecked (- [ ]), "completed" for checked (- [x]), or "all" for both.', default: 'open', }, owner: { type: 'string', description: 'Case-insensitive substring filter matching the extracted @owner or **Owner**: assignee (e.g. "Alice"). Leave empty to include unassigned and all owners.', default: '', }, limit: { type: 'integer', description: 'Maximum number of action items to return (clamped between 1 and 200).', default: 50, minimum: 1, maximum: 200, }, }, }, } 4. Three Publishing Gotchas Across npm, Official MCP Registry & Docker Registry
If you plan to distribute your MCP server across all three registries from one repository, watch out for these exact pitfalls:
- Package ownership verification (
mcpName): The Official MCP Registry (registry.modelcontextprotocol.io) verifies npm ownership by fetchinghttps://registry.npmjs.org/<pkg>/<version>and asserting thatpackage.jsoncontains a matching"mcpName": "io.github.<org>/<repo>"field. Wait for npm's CDN propagation (direct/<version>returningHTTP 200) before runningmcp-publisher publish, or the registry validator will return400(404on the newly published version). - GitHub Organization namespaces require
read:org: Running interactivemcp-publisher login githubonly authorizes your personal namespace (io.github.<username>/*). Publishing under an org namespace (io.github.<org>/*) returns403 Forbiddenunless you authenticate with a token carryingread:org(e.g.,mcp-publisher login github --token "$(gh auth token)"or GitHub Actions OIDC). - Keep
serverInfo.version,package.json,server.json, and GitHub Releases in lockstep: Validators and maintenance scorers cross-check all four. Adding a single unit test that assertsinitializereturnspackage.json.versionand that every tool definestitle,annotations.readOnlyHint === true, and non-empty parameter descriptions prevents drift permanently:
npx -y okf-wiki-mcp --vault ./examples stats Source & References
- Server source (MIT, zero runtime deps): github.com/onemira-space/okf-wiki-mcp · npmjs.com/package/okf-wiki-mcp
- Companion OKF v0.2 Markdown linter & converter (MIT): github.com/onemira-space/okf-markdown · npmjs.com/package/okf-markdown
- Local MCP integration architecture notes: onemira.com/docs/mcp-integration
If you have hit other edge cases shipping stdio MCP servers inside read-only containers or across registry validators, I would love to compare notes in the comments.