mcp-readonly-code-server

Minimal Node + TypeScript example project for a read-only MCP server that exposes one local code workspace to an AI client over stdio.

Project position

This repository is currently an example project, not a production-ready remote service.

It demonstrates how to:

• build a read-only MCP server with the official TypeScript SDK

• expose one local workspace root safely

• serve MCP resources and a simple search tool over stdio

• enforce basic deny rules for sensitive paths and file types

Related MCP server: mcp-file-lens

What this project exposes

• Official MCP TypeScript SDK wired through McpServer

• stdio bootstrap entry for local MCP hosts

• Three read-only resources:

  • repo://overview

  • repo://tree/{path}

  • repo://file/{path}

• One read-only tool:

  • search_code

• A path guard that keeps all file access inside one workspace root

• A sample-private-code/ directory for local smoke testing

Current behavior

This build exposes a real read-only code workspace through MCP resources plus one minimal search tool:

• repo://overview explains the boundary and available surface

• repo://tree/{path} lists files and directories under an allowed subtree

• repo://file/{path} reads one allowed text file

• search_code recursively searches text files and returns line-level matches

Safety rules:

• all access stays inside WORKSPACE_ROOT

• denied directories: .git, node_modules, dist, coverage

• denied suffixes: .env, .pem, .key, .crt

• binary and oversized files are rejected

Install

npm install

Run

Start the server in development mode:

npm run dev

By default, it exposes this sample directory:

sample-private-code/

Specify the project directory

Use WORKSPACE_ROOT to choose which local project the MCP server exposes.

Expose the sample directory explicitly:

WORKSPACE_ROOT=/home/zsp0509/node-projects/mcp-readonly-code-server/sample-private-code npm run dev

Expose this repository itself:

WORKSPACE_ROOT=/home/zsp0509/node-projects/mcp-readonly-code-server npm run dev

Expose another project:

WORKSPACE_ROOT=/path/to/your-project npm run dev

If the path contains spaces, quote it:

WORKSPACE_ROOT="/home/zsp0509/My Projects/app" npm run dev

Notes:

• use an absolute path

• one server instance exposes one workspace root

• if you need multiple projects, configure multiple MCP server entries with different WORKSPACE_ROOT values

How agents call it

This project is a stdio MCP server.

That means:

• it does not open an HTTP port

• an MCP host starts the process directly

• the host communicates with it through stdin and stdout

There are two common ways to use it:

1. Manual local run

You start it yourself in a terminal:

WORKSPACE_ROOT=/path/to/your-project npm run dev

In this mode, the process must keep running. If you stop it, the agent cannot call it.

2. Host-managed run

You register it in an MCP-capable host such as an inspector or desktop client.

In this mode, the host usually starts the process automatically when needed. You do not need to keep a separate terminal open.

Example MCP host configuration

Development command:

{
  "command": "node",
  "args": [
    "--import",
    "tsx",
    "/home/zsp0509/node-projects/mcp-readonly-code-server/src/index.ts"
  ],
  "env": {
    "WORKSPACE_ROOT": "/path/to/your-project"
  }
}

Built command:

{
  "command": "node",
  "args": [
    "/home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.js"
  ],
  "env": {
    "WORKSPACE_ROOT": "/path/to/your-project"
  }
}

Multiple project host configuration

If you want one agent host to access multiple projects, register multiple MCP server entries.

Each entry uses the same server program but a different WORKSPACE_ROOT.

Example:

{
  "mcpServers": {
    "crm-code": {
      "command": "node",
      "args": [
        "/home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.js"
      ],
      "env": {
        "WORKSPACE_ROOT": "/srv/projects/crm"
      }
    },
    "admin-panel-code": {
      "command": "node",
      "args": [
        "/home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.js"
      ],
      "env": {
        "WORKSPACE_ROOT": "/srv/projects/admin-panel"
      }
    }
  }
}

In that setup:

• crm-code exposes only /srv/projects/crm

• admin-panel-code exposes only /srv/projects/admin-panel

• each server process keeps its own workspace boundary

You can do the same with the development entrypoint:

{
  "mcpServers": {
    "crm-code-dev": {
      "command": "node",
      "args": [
        "--import",
        "tsx",
        "/home/zsp0509/node-projects/mcp-readonly-code-server/src/index.ts"
      ],
      "env": {
        "WORKSPACE_ROOT": "/srv/projects/crm"
      }
    },
    "admin-panel-code-dev": {
      "command": "node",
      "args": [
        "--import",
        "tsx",
        "/home/zsp0509/node-projects/mcp-readonly-code-server/src/index.ts"
      ],
      "env": {
        "WORKSPACE_ROOT": "/srv/projects/admin-panel"
      }
    }
  }
}

Use different server names so the host can distinguish them clearly.

Common host examples

Different MCP hosts may wrap server definitions differently, but the important part stays the same:

• the command points to this server

• each project gets its own server entry

• each entry sets a different WORKSPACE_ROOT

Claude Desktop style

Some hosts use a top-level mcpServers object like this:

{
  "mcpServers": {
    "crm-code": {
      "command": "node",
      "args": [
        "/home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.js"
      ],
      "env": {
        "WORKSPACE_ROOT": "/srv/projects/crm"
      }
    },
    "admin-panel-code": {
      "command": "node",
      "args": [
        "/home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.js"
      ],
      "env": {
        "WORKSPACE_ROOT": "/srv/projects/admin-panel"
      }
    }
  }
}

If you want to use the TypeScript entry during development, replace the command arguments with:

[
  "--import",
  "tsx",
  "/home/zsp0509/node-projects/mcp-readonly-code-server/src/index.ts"
]

Cherry Studio style

If your host asks you to add one MCP server at a time in a form or list UI, create two separate local command entries:

Server 1:

{
  "name": "crm-code",
  "command": "node",
  "args": [
    "/home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.js"
  ],
  "env": {
    "WORKSPACE_ROOT": "/srv/projects/crm"
  }
}

Server 2:

{
  "name": "admin-panel-code",
  "command": "node",
  "args": [
    "/home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.js"
  ],
  "env": {
    "WORKSPACE_ROOT": "/srv/projects/admin-panel"
  }
}

If the UI exposes separate fields instead of raw JSON, fill them like this:

• Name: crm-code

• Command: node

• Args: /home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.js

• WORKSPACE_ROOT: /srv/projects/crm

Then add a second entry with a different name and project path.

Practical notes

• prefer the built entrypoint dist/src/index.js for long-term use

• use the src/index.ts entrypoint mainly for local development

• if your host uses a different outer JSON shape, keep the inner command, args, and env.WORKSPACE_ROOT values the same

Build

Build the TypeScript output:

npm run build

Run the built server:

WORKSPACE_ROOT=/path/to/your-project npm run start

Smoke test

Run the in-process MCP client validation script:

npm run smoke

It validates:

• repo://overview

• repo://tree/{+path}

• repo://file/{+path}

• search_code

• denied-path rejection for .git/config

Inspector checklist

If you want to verify the real stdio workflow with an MCP inspector or host:

1. Start the server or register the command in your host.

2. Point the inspector or host command at:

node --import tsx src/index.ts

3. Set WORKSPACE_ROOT to the project you want to expose.

4. Verify these calls:

• read repo://overview

• read repo://tree/controllers

• read repo://file/controllers/user-controller.ts

• call search_code with {"query":"return","path":"controllers"}

• try denied path repo://file/.git/config

Limitations

Current scope:

• stdio transport only

• one workspace root per process

• read-only resources and one minimal text search tool

If you want to deploy this on a remote server for agents on other machines, you would typically add an HTTP-based MCP transport in a follow-up implementation.