沙盒 + 文件工具
概览
一个学校项目：一个小型模型上下文协议（MCP）服务器，用 TypeScript 编写，允许 MCP 客户端（AI 代理）处理指定工作区/文件夹内的文件，无法访问外部文件。 该项目分为五个里程碑。服务器目前注册并支持stdio和可流式HTTP传输。M5认证和工作流程代码已实现;部分环境特定和实时演示检查仍需在部署的机器上验证。 先按照下面的设置和测试说明操作，然后阅读你想运行功能的里程碑指南。表格描述了项目的里程碑进展;这并不意味着ngrok、Windows或实时远程多代理演示已经在所有环境中得到验证。 这些里程碑是相互建立的。如果你是从GitHub搭建仓库，先从通用设置开始，然后使用匹配的里程碑部分。 - 安装节点。
概述（AI 翻译）
一个学校项目：一个小型模型上下文协议（MCP）服务器，用TypeScript编写，允许MCP客户端（AI代理）处理指定workspace/文件夹内的文件，无法访问该文件夹外的任何东西。
项目状态：M1–M5已实施
该项目分为五个里程碑。服务器目前注册了17个MCP工具，并支持stdio和可流式HTTP传输。M5认证和工作流程代码已实现;部分环境特定和实时演示检查仍需在部署的机器上验证。
里程碑路线图
| 里程碑 | 构建内容 | 主文件/功能 | 验证 |
|---|---|---|---|
| M1 — 项目骨架 | TypeScript MCP 服务器基础和初始 list_files 工具。 |
src/server.ts， package.json， tsconfig.json |
安装依赖，构建并启动stdio服务器/MCP Inspector。 |
| M2 — 核心文件工具和沙盒 | 五个带有路径验证的工作区文件工具，将文件访问限制在workspace/内;文本文件大小限制。 |
src/tools.ts;list_files， read_file， write_file， str_replace， delete_file |
npm test |
本页由 AI 翻译，技术细节请以原文为准。
README
以下为原文 README 节选，完整内容请查看原文。
MCP File Server
A school project: a small Model Context Protocol (MCP) server, written in TypeScript, that lets an MCP client (an AI agent) work with files inside a designated workspace/ folder, and cannot reach anything outside it.
Project status: M1–M5 implemented
The project is organized into five milestones. The server currently registers 17 MCP tools and supports both stdio and Streamable HTTP transports. M5 authentication and workflow code is implemented; some environment-specific and live-demo checks still need to be verified on the machine where you deploy it.
Milestone roadmap
| Milestone | What was built | Main files / features | Verification |
|---|---|---|---|
| M1 — Project skeleton | TypeScript MCP server foundation and initial list_files tool. |
src/server.ts, package.json, tsconfig.json |
Install dependencies, build, and launch the stdio server / MCP Inspector. |
| M2 — Core file tools and sandbox | Five workspace file tools with path validation to keep file access inside workspace/; text-file size limits. |
src/tools.ts; list_files, read_file, write_file, str_replace, delete_file |
npm test |
| M3 — HTTP deployment | Streamable HTTP endpoint at /mcp, endpoint checker, ngrok tunnelling instructions, and PM2 process configuration. |
src/server-http.ts, test/m3-http-test.ts, ecosystem.config.cjs |
npm run test:http; then verify the local endpoint. ngrok and Windows deployment require local checks. |
| M4 — Agent handoff and workspace utilities | Shared state/plan/checkpoint/decision files, read-only Git status/diff/log tools, and workspace text search. | src/handoff.ts, src/git-tools.ts, src/search.ts, workspace/ |
npm run test:m4 |
| M5 — Authentication and multi-step workflow | Bearer-token authentication for HTTP requests plus a documented workflow for agents to hand off work through shared project-state files. | MCP_AUTH_TOKEN; auth checks in the HTTP tests; handoff tools from M4 |
npm run test:all; verify valid and invalid tokens locally and demonstrate a handoff with your MCP client. |
Recommended order for a new user: follow the setup and testing instructions below first, then read the milestone guide for the feature you want to run. The table describes the project’s milestone progression; it does not mean ngrok, Windows, or a live remote multi-agent demonstration have already been verified in every environment.
Remote MCP client --HTTPS--> ngrok URL --> localhost:3000 --> /mcp --> check the token --> MCP server --> workspace/
Follow the milestones
These milestones build on one another. If you are setting up the repository from GitHub, start with the common setup, then use the matching milestone section.
Before you start
- Install Node.js 18.18 or newer and npm.
- Install Git and make sure it is available in your terminal.
安装
This server does not publish a one-line install command.
Open the repository installation guide 新手？先看 mcpskill.org 教程 →