mcp-readonly-code-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-readonly-code-server list files in the src directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
stdioenforce basic deny rules for sensitive paths and file types
Related MCP server: TimeVerse Code Reader
What this project exposes
Official MCP TypeScript SDK wired through
McpServerstdiobootstrap entry for local MCP hostsThree read-only resources:
repo://overviewrepo://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://overviewexplains the boundary and available surfacerepo://tree/{path}lists files and directories under an allowed subtreerepo://file/{path}reads one allowed text filesearch_coderecursively searches text files and returns line-level matches
Safety rules:
all access stays inside
WORKSPACE_ROOTdenied directories:
.git,node_modules,dist,coveragedenied suffixes:
.env,.pem,.key,.crtbinary and oversized files are rejected
Install
npm installRun
Start the server in development mode:
npm run devBy 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 devExpose this repository itself:
WORKSPACE_ROOT=/home/zsp0509/node-projects/mcp-readonly-code-server npm run devExpose another project:
WORKSPACE_ROOT=/path/to/your-project npm run devIf the path contains spaces, quote it:
WORKSPACE_ROOT="/home/zsp0509/My Projects/app" npm run devNotes:
use an absolute path
one server instance exposes one workspace root
if you need multiple projects, configure multiple MCP server entries with different
WORKSPACE_ROOTvalues
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
stdinandstdout
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 devIn 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-codeexposes only/srv/projects/crmadmin-panel-codeexposes only/srv/projects/admin-paneleach 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-codeCommand:nodeArgs:/home/zsp0509/node-projects/mcp-readonly-code-server/dist/src/index.jsWORKSPACE_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.jsfor long-term useuse the
src/index.tsentrypoint mainly for local developmentif your host uses a different outer JSON shape, keep the inner
command,args, andenv.WORKSPACE_ROOTvalues the same
Build
Build the TypeScript output:
npm run buildRun the built server:
WORKSPACE_ROOT=/path/to/your-project npm run startSmoke test
Run the in-process MCP client validation script:
npm run smokeIt validates:
repo://overviewrepo://tree/{+path}repo://file/{+path}search_codedenied-path rejection for
.git/config
Inspector checklist
If you want to verify the real stdio workflow with an MCP inspector or host:
Start the server or register the command in your host.
Point the inspector or host command at:
node --import tsx src/index.tsSet
WORKSPACE_ROOTto the project you want to expose.Verify these calls:
read
repo://overviewread
repo://tree/controllersread
repo://file/controllers/user-controller.tscall
search_codewith{"query":"return","path":"controllers"}try denied path
repo://file/.git/config
Limitations
Current scope:
stdiotransport onlyone 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.
Available Tools
1 toolsearch_codeB
Search text matches inside the configured read-only workspace root.
Inputs: query (required), path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion between tools. The single tool's purpose is clearly defined.
The sole tool 'search_code' follows a clear verb_noun pattern, making its purpose immediately understandable. Consistency is trivially maintained.
A read-only code server with only one tool feels excessively limited. Typically, such a server would need multiple tools (e.g., list files, read file content) to be useful, making a single tool insufficient for the apparent scope.
The toolset is severely incomplete for a read-only code server. Essential operations like listing files or reading file contents are missing, leaving agents unable to perform basic code exploration tasks.
Related MCP Connectors
Read-only MCP server exposing a user ORANO library to their own AI agent.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA secure MCP server enabling read-only access and file search capabilities within a specified directory, while respecting .gitignore patterns.MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for code reading with intelligent caching, line-range selection, and language detection, enabling AI assistants to efficiently and safely explore file systems.MIT
- FlicenseAqualityDmaintenanceA read-only MCP server that enables AI assistants to search files, list directories, retrieve system info, and get file metadata on the local file system.4-
- FlicenseAqualityDmaintenanceA read-only MCP server that lets Claude read and search source code from local project folders, with path containment security.4-