Local Knowledge Desk MCP Demo

Local Knowledge Desk MCP Demo

Local Knowledge Desk is a small TypeScript server that teaches the core ideasbehind the Model Context Protocol (MCP). It lets Codex create, list, read,search, summarize, and delete local Markdown notes.

The MCP server and its note data are fully local. The server needs no API key,database, hosted service, or separate account. Codex may still use its normalauthenticated model service. Notes remain ordinary files that you can inspectwith any text editor.

MCP mental model

In this demo:

• Codex is the MCP host/client. It launches the configured server,discovers its capabilities, and decides when to use them.
• This Node.js process is the MCP server. It advertises capabilities andhandles requests from Codex.
• Tools perform actions. For example, create_note writes a file andsearch_notes searches the local collection.
• Resources expose context. Each note can be discovered and read through anote://<id> URI.
• Prompts package reusable workflow instructions. They tell Codex how tocombine capabilities, but prompts do not call tools themselves. Codex readsthe prompt instructions and then makes any tool calls.

flowchart LR
    A["Codex host/client"] --> B["MCP over stdio"]
    B --> C["TypeScript server<br/>dist/src/index.js"]
    C --> D["Markdown notes<br/>data/notes/*.md"]
    D --> C
    C --> B
    B --> A

stdio is the transport: MCP protocol messages travel through the serverprocess's standard input and standard output.

Prerequisites

• Node.js 20 or newer
• npm

Check your installation:

node --version
npm --version

Setup

From the repository root:

npm install
npm run build
npm test

Run the build before opening Codex. The generated dist/ directory is ignoredby Git, so it does not exist in a fresh checkout. Codex cannot launchdist/src/index.js until npm run build has created it.

If npm install fails behind a corporate TLS proxy withUNABLE_TO_VERIFY_LEAF_SIGNATURE and your Node version supports--use-system-ca, tell Node to use the operating system's CA store for thecurrent PowerShell session, then retry:

$env:NODE_OPTIONS='--use-system-ca'
npm install

Check node --help for --use-system-ca. On older Node releases, update Nodeor ask your administrator for the proxy certificate and configureNODE_EXTRA_CA_CERTS instead.

Connect Codex

The project-scoped .codex/config.toml contains:

[mcp_servers.local-knowledge-desk]
command = "node"
args = ["dist/src/index.js"]
cwd = "."
startup_timeout_sec = 10
tool_timeout_sec = 30
enabled = true

This tells Codex to start the compiled server with Node, communicate overstdio, and use the repository root as the working directory.

Make sure the repository is trusted in Codex so project-scoped configurationcan load. After building, open a new Codex session from this repository.Project MCP configuration is loaded when a session starts; an already-opensession may not notice a newly built server or changed configuration.

Try the demo

Ask Codex requests such as:

1. List the tools, resources, and prompts provided by the Local Knowledge Desk.
2. Create a note called mcp-basics titled MCP Basics with the body "Tools perform actions. Resources expose context. Prompts provide reusable workflow instructions."
3. Search my notes for resources.
4. List the available note resources.
5. Read note://mcp-basics.
6. Use the daily_review prompt.
7. Use the research_digest prompt with the topic "MCP resource design".
8. Delete mcp-basics, but ask me to confirm before deleting it.

The final request matters: Codex should obtain your confirmation beforecalling delete_note with confirm: true.

Capabilities

Tools

The server exposes exactly six tools:

Resources

The resource URI template is exactly:

note://{id}

For example, the note stored as data/notes/mcp-basics.md is available asnote://mcp-basics. Resource discovery lists existing notes, and reading aresource returns text/markdown.

Prompts

The server exposes exactly two prompts:

Again, these prompts return instructions. They do not executelist_notes, search_notes, or read_note by themselves.

Local data

Notes are UTF-8 Markdown files under:

data/notes/*.md

Each file uses this format:

# Note Title

Note body.

The filename is the note ID, such as mcp-basics.md. You can inspect or backup these files with normal local tools. Runtime notes are ignored by Git bydefault; change .gitignore deliberately if you want to version them. Theserver creates data/notes/ when needed. Set KNOWLEDGE_DESK_NOTES_DIR beforelaunching the server to use another notes directory.

Project guide

Extend the server

Add a tool

1. Add any required storage method in src/note-store.ts.
2. Register the tool with server.registerTool(...) in src/server.ts.
3. Define a Zod input schema and accurate MCP annotations.
4. Add storage tests and protocol-level tests.
5. Run npm run build so Codex launches the new compiled code.

Add a resource

1. Decide on a stable URI or URI template.
2. Register it with server.registerResource(...) in src/server.ts.
3. Return the correct MIME type and avoid exposing internal filesystem paths.
4. Test resource discovery and reading.

Add a prompt

1. Register it with server.registerPrompt(...) in src/server.ts.
2. Add a Zod argument schema when the workflow needs inputs.
3. Return clear workflow instructions that name the relevant tools.
4. Test prompt discovery, argument validation, and returned messages.

Prompts should remain instructions. Tool execution belongs to the host/client.

Safety model

This is a local-user teaching demo, not a hardened multi-user service or asecurity boundary against a hostile administrator:

• Note IDs allow only lowercase ASCII letters, digits, and internal hyphens,with a maximum length of 64 characters. Windows device names and pathtraversal forms are rejected.
• Resolved note paths must remain beneath the configured notes root.
• Creation uses exclusive file creation, so an existing note is notoverwritten, including during concurrent creates.
• Deletion requires confirm: true, and the server instructions tell Codex toask for user intent first.
• The notes root must be a real directory rather than a symbolic link. Notereads and deletes reject non-regular files, including symbolic links.
• Unexpected storage errors are logged to stderr while clients receive thesanitized message Unexpected local storage error. Internal paths are notreturned through MCP.

On platforms that provide O_NOFOLLOW, reads use it to avoid following asymlink at open time. Windows does not provide the same Node.js flag, so thereis a residual check/open race: a highly privileged local process that replacesa checked file concurrently may beat the safety checks. That limitation isacceptable for this local-user demo, but a hostile multi-user deployment needsstronger OS-level isolation and filesystem controls.

Troubleshooting

Codex shows no Local Knowledge Desk tools

• Confirm npm run build completed successfully.
• Confirm dist/src/index.js exists.
• Confirm the repository is trusted so Codex may load .codex/config.toml.
• Start a new Codex session from the repository root so.codex/config.toml is loaded.
• Check that Node.js 20 or newer is available as node.

Codex is using stale behavior

TypeScript changes do not update dist/ automatically. Run:

npm run build

Then start a new Codex session so the server process uses the rebuilt files.

The stdio connection breaks after adding logging

Do not write ordinary logs to stdout. Stdout is reserved for MCP protocolmessages, and extra text can corrupt the connection. Send diagnostics tostderr with console.error(...).

The server starts in the wrong directory

The default notes path is resolved from the server's working directory.Codex uses cwd = "." from the repository-scoped configuration. Other hostsshould set a correct working directory, use absolute paths, or setKNOWLEDGE_DESK_NOTES_DIR.

On Windows, prefer absolute paths and remember to escape backslashes insideJSON strings, for example D:\\Projects\\local-knowledge-desk.

npm reports a TLS certificate error

For UNABLE_TO_VERIFY_LEAF_SIGNATURE behind a managed corporate proxy, firstcheck whether node --help lists --use-system-ca. If it does, retry inPowerShell with:

$env:NODE_OPTIONS='--use-system-ca'
npm install

If that flag is unavailable, update Node or configure your organization's CAcertificate through NODE_EXTRA_CA_CERTS.

Optional: Claude Desktop

Claude Desktop can launch the same stdio server. Build first, then add an entrylike this to the Claude Desktop MCP configuration:

{
  "mcpServers": {
    "local-knowledge-desk": {
      "command": "node",
      "args": [
        "D:\\REPLACE\\WITH\\ABSOLUTE\\PATH\\local-knowledge-desk\\dist\\src\\index.js"
      ],
      "env": {
        "KNOWLEDGE_DESK_NOTES_DIR": "D:\\REPLACE\\WITH\\ABSOLUTE\\PATH\\local-knowledge-desk\\data\\notes"
      }
    }
  }
}

Replace both clearly marked Windows paths with absolute paths on your machine.The env block is optional; omit it to use data/notes relative to ClaudeDesktop's server working directory. Using an absoluteKNOWLEDGE_DESK_NOTES_DIR is less ambiguous. Restart Claude Desktop afterchanging its configuration.

On macOS or Linux, use the same JSON structure with absolute POSIX paths, suchas /Users/you/projects/local-knowledge-desk/dist/src/index.js.

Development commands

npm run build       # Compile TypeScript into dist/
npm test            # Run the test suite once
npm run test:watch  # Run tests in watch mode
npm start           # Start the compiled stdio server

When running npm start directly, the process may appear idle. That is normal:it is waiting for an MCP client to communicate over stdio.