local-mcp-simple-server

A deliberately small MCP server that isolates one complete interaction:

one selected file → one MCP tool call → bounded source text → Copilot explains it

It exposes exactly one tool, read_source_file. There is no inventory, no search, no Git integration, no model client, and no second tool. This is the MCP counterpart to local-llm-simple-harness: it exists so the mechanics of one MCP round trip are easy to see end-to-end, before looking at a larger system (modernization-evidence-harness) that builds inventory, search, excerpts, provenance, and artifact-reference validation on top of the same basic shape.

This is an independent learning project. It does not import, depend on, or require either the simple LLM harness or the evidence harness.

What this is not

• Not a sandbox. The containment checks in server.js (resolving ..-free relative paths, then following symlinks with fs.realpath to confirm the real file is still under the configured root) are ordinary application-level checks, not an OS-level security boundary. They stop a well-formed MCP client from reading outside the configured root; they do not defend against a hostile process racing the filesystem underneath this one (a file swapped out between the containment check and the read that follows). Run this server with the same trust you'd give any local process that reads files on your behalf.

• Not a text-content guarantee. "UTF-8 text file" is enforced by two cheap, honest checks: reject any file containing a NUL byte, then require the remaining bytes to decode as strict UTF-8 (TextDecoder with fatal: true). This reliably rejects binary formats (images, archives, compiled binaries) but cannot prove a file is meaningful source code — a valid UTF-8 file full of nonsense still passes, and in principle a binary format could (rarely) decode as valid UTF-8 too. Good enough to keep this tool from handing binary garbage to an LLM; not a general file-type classifier.

• Not versioned or attributed. The tool reads whatever is on disk right now. There is no Git subprocess, no commit pinning, no hash, and no provenance record — if you need "prove this exact text existed at this exact revision," that's what the larger evidence harness is for.

Related MCP server: Project Files Read-only MCP

Requirements

• Node.js 18 or newer, native ESM.

• npm (a lockfile is committed; use npm ci for a reproducible install).

Setup

cd local-mcp-simple-server
npm ci

Configure the one thing this server needs — an absolute path to the directory it's allowed to read from — via SIMPLE_MCP_SOURCE_ROOT. The tool caller (Copilot) never sees or changes this value; it is fixed for the life of the server process.

Run it directly to confirm it starts (single-line PowerShell, no heredocs):

$env:SIMPLE_MCP_SOURCE_ROOT = "C:\path\to\local-mcp-simple-server\examples\source"; node server.js

Why this appears to hang

server.js prints a one-line "ready" banner to stderr and then waits. That's correct, not broken: a stdio MCP server has no interactive prompt — it is a subprocess meant to be launched and driven by an MCP client (VS Code / Copilot, or the test client in this repo) that writes JSON-RPC requests to its stdin and reads responses from its stdout. Run standalone in a terminal, it will sit there silently (aside from that one stderr line) until something speaks the protocol to it, or until you close its stdin (Ctrl+C, or closing the terminal) to stop it.

VS Code / Copilot setup (Windows)

1. Copy examples/vscode.mcp.json into your workspace's .vscode/mcp.json (single-line PowerShell):

   Copy-Item "examples\vscode.mcp.json" ".vscode\mcp.json" -Force

2. Edit the copied file so SIMPLE_MCP_SOURCE_ROOT points at an absolute path on your machine (the checked-in example uses ${workspaceFolder}/examples/source, which VS Code expands for you, so this step may already be correct if you keep the same layout).

3. Open the Command Palette and run MCP: List Servers, confirm local-mcp-simple-server is listed, and start it from there if it isn't already running.

4. Open Copilot Chat in Agent mode. Ask it to use the read_source_file tool (name it explicitly) to read examples/source/CustomerService.vb and explain its validation behavior.

5. Check the tool-call record before trusting the answer. Copilot's chat UI shows which tool actually ran for a turn. Confirm it says read_source_file from local-mcp-simple-server — not a built-in workspace file read. A built-in read can produce a similar-looking explanation without ever going through this server, which would silently defeat the point of the smoke test.

Verified 2026-09-21 against live VS Code Copilot Chat (Agent mode, Windows) reading this repo's own CustomerService.vb fixture. The MCP output log showed the server start under VS Code's MCP client (Discovered 1 tools), and the chat transcript's tool-call record showed tool: "mcp_local-mcp-sim_read_source_file" with args: {"path":"CustomerService.vb"} — the mcp_-prefixed tool name confirms the call went through this server rather than a built-in workspace file read. The raw response was {"path":"CustomerService.vb","text":"..."}, the complete file text untouched (CRLF preserved), and Copilot's explanation of the validation logic (name non-blank; email needs exactly one interior @; phone reduces to digit characters via Char.IsDigit and requires exactly 10, correctly noting this includes Unicode digits, not just ASCII) matched the actual code.

What the SDK handles vs. what this code handles

We never hand-write JSON-RPC or MCP framing — the SDK owns the wire format entirely. Our job is exactly the part inside the tool callback: turn one validated path into either a result or a clear, catchable error.

Why no model client lives in this server

Copilot supplies its own reasoning; this server supplies bytes. VS Code's Copilot already has a configured chat model and calls this MCP server as a tool mid-conversation — the server's job ends the moment it returns text. There is deliberately no API key, no model SDK, and no prompt construction here: adding one would blur exactly the boundary this milestone exists to make visible (server = context, Copilot = reasoning).

Where the text you return actually goes

Whatever read_source_file returns is inserted into Copilot's ongoing chat context and sent to whatever model backs your Copilot subscription and its currently configured processing environment/region — the same as if you'd pasted the file into the chat yourself. Only put synthetic, non-sensitive files under a directory you point SIMPLE_MCP_SOURCE_ROOT at for real use; the fixtures in this repo (examples/source/) are intentionally synthetic for exactly this reason.

How this maps onto the larger evidence harness

modernization-evidence-harness performs the same kind of step — hand a bounded slice of source to an LLM — but wraps it with repository inventory (which files exist), search (which file is relevant), excerpting (which lines matter), and provenance (proving what revision the text came from). This server is that one step by itself: given a path someone already picked, read it safely and hand back the whole thing. If you can explain how a call reaches server.js's tool callback and how its result gets back to Copilot, you've understood the piece the bigger harness builds on.

Function-by-function walkthrough of one call

Given a request to read CustomerService.vb:

1. VS Code / Copilot sends a tools/call JSON-RPC request over the server's stdin. The MCP SDK's StdioServerTransport reads and parses it; this code never touches raw stdin.

2. McpServer (SDK) looks up the registered read_source_file tool, validates { path: "CustomerService.vb" } against the Zod inputSchema, and — only if that passes — invokes the callback registered in registerReadSourceFileTool.

3. readSourceFile(sourceRootReal, rawPath) is the composition of the actual policy, in order:

   • normalizeRelativePath(rawPath) — pure, no filesystem access. Splits on / or \, rejects an absolute-looking path, and rejects any .. segment. Returns a normalized, forward-slash relative path.

   • resolveRealPathWithinRoot(sourceRootReal, normalizedPath) — joins the path onto the root, calls fs.realpath (which follows every symlink/junction in the chain), and confirms the real result is still inside the real root via path.relative.

   • assertRegularFile(realPath, normalizedPath) — fs.stat and rejects anything that isn't a plain file (a directory, in particular).

   • readBoundedFile(realPath) — streams the file in 16 KiB chunks, throwing the moment the running total passes 64 KiB, so an oversized file is never fully buffered before being rejected.

   • decodeUtf8Text(buffer, normalizedPath) — rejects a NUL byte, then strictly decodes the rest as UTF-8.

4. On success, the callback returns an ordinary object — { structuredContent: { path, text }, content: [{ type: "text", ... }] } — straight back to McpServer, which validates it against the outputSchema and serializes it as the tools/call response.

5. On any failure at any step above, the callback's catch calls toToolErrorResult(error), which returns { isError: true, content: [...] } instead of throwing. This is what satisfies "return understandable tool errors without terminating the server": the exception never reaches the SDK or the transport, so the process and the stdio connection to it both stay alive for the next call.

6. StdioServerTransport (SDK) serializes that result and writes it to stdout; Copilot reads it back as the tool's output and continues the conversation with it in context.

Testing

npm test

Uses Node's built-in test runner (node --test) against test/server.test.js. That file starts one real server subprocess via the SDK's StdioClientTransport/Client — exactly the way a real MCP client would — and reuses it across the whole suite (bounded by --test-timeout=15000; the client and its fixtures are torn down in an after hook regardless of pass/fail).

Covered:

• discovery lists exactly read_source_file;

• a synthetic fixture round-trips its expected relative path and text;

• malformed arguments (missing path, wrong type);

• missing file, a directory instead of a file, an absolute path, .. traversal;

• an oversized file is rejected, not truncated (structuredContent is absent on that result);

• unsupported (binary) content is rejected;

• a symlink escaping the source root is rejected — skipped with an explanation if the test environment can't create a symlink (e.g. Windows without permission to create one), rather than failing;

• the server answers a normal call correctly after several failed calls;

• the server's stderr banner is captured and asserted on directly, and every other test having round-tripped valid JSON-RPC over stdout is itself evidence that no stray diagnostic corrupted the protocol stream.

Known acceptance gaps

• Symlink/junction-escape rejection is exercised on Linux in this environment; Windows junction behavior relies on Node's fs.realpath resolving junctions the same way it resolves symlinks, which is documented Node behavior but has not been separately verified on Windows here.

Non-goals (out of scope for this milestone, on purpose)

Repository inventory or search, multiple source roots, Git subprocesses or revision pinning, evidence catalogs or artifact validation, a model client or API key, MCP sampling/prompts/resources/HTTP transport/auth, file writes, shell tools, database storage, a UI, Docker/deployment, or any plugin/agent/extensibility scaffolding. All of that belongs to modernization-evidence-harness, not here.