mcpField
L
local-workspace-mcp

local-workspace-mcp

本地服务
github.com/peter4leadson文件与存储02 周前更新

关于 local-workspace-mcp

local-workspace-mcp 是面向 AI 助手的只读 MCP 服务,为本地工作区提供受限访问。它结合文件系统与 Git 检查及允许列表任务,不提供写入、删除或任意 Shell 工具。

主要功能

  1. 01受限的文件读取与搜索
  2. 02只读 Git 状态、差异、日志和内容查看
  3. 03图像、压缩包、PDF 与 Office 文件检查
  4. 04由操作者配置工作区根目录和拒绝规则
  5. 05带输出限制的允许列表命名任务

适用场景

  1. 01在不授予工作区写权限的情况下检查文件
  2. 02查看未提交更改和仓库历史
  3. 03检查授权工作区中的图像与文档
  4. 04在不开放任意 Shell 的情况下运行预定义任务

MCP 相关

通过 stdio JSON-RPC 向 MCP 客户端提供 23 个工具。文件系统和 Git 工具以只读为主;task_run 仅运行操作者列入允许列表的命令。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"peter4leadson-local-workspace": {
"command": "npx",
"args": [
"-y",
"local-workspace-mcp"
]
}
}
}
启动命令npx -y local-workspace-mcp

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
npmlocal-workspace-mcp0.2.2

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

本地工作区 MCP 图标

local-workspace-mcp

你的 AI 助手需要上下文,但不需要不受限制的访问权限。

一个面向本地工作区、以读取为主的 MCP 服务。它不提供写入、删除或 任意 Shell 工具。不是受到限制或被禁用,而是根本不存在。每个 文件系统路径都会根据操作员授权的根目录以及默认拒绝列表进行检查,列表涵盖机密、 .env 文件、私钥和 .git 内部文件。Git 读取工具和由操作员声明的命名任务提供 受限能力,而无需向模型开放 Shell。

  • 23 个工具,通过 stdio JSON-RPC 提供:受限的文件系统读取/搜索、 只读 Git(状态/差异/日志/显示/分支)、多模态文件检查 (图像/压缩包/PDF/Office),以及用于 显式加入允许列表的命令的 task_run。
  • **一种传输方式:**每个 MCP 宿主都会启动 workspace-mcp serve --stdio。 服务本身没有入站监听器,不会作为守护进程运行,也不会发起 网络调用(允许列表中的任务会以你的用户身份运行,且不受 网络限制;下文所述的 ChatGPT 隧道路径会运行受监督的 tunnel-client 进程,而不是由宿主启动的进程)。
  • 明确说明能力范围:task_run 会以你的用户身份执行实际命令。允许列表限制的是 可以调用的内容,而不是被调用代码能做什么。 它不是沙箱。

正在评估是否供团队使用?请从 docs/THREAT-MODEL.md 和 SECURITY.md 开始。

目录: 问题所在 · 快速开始 · 用法 · 工具范围 · 支持的宿主 · 权限模型 · 它不会做什么 · 安全架构 · 配置 · 故障排除 · 兼容性 · 验证构建 · 发布状态

问题所在

宿主内置的文件工具虽然方便,却处于客户端的权限处理流程中;用户会因疲惫而绕过这一流程 (--dangerously-skip-permissions、“全部同意”)。官方的 @modelcontextprotocol/server-filesystem 提供读取和写入工具, 且没有默认的机密拒绝列表,并且已经覆盖过用户的 .env(上游问题 #1869)。通用文件系统 MCP 会让模型访问文件,但不会提供_受限_访问权限。

该服务将边界移至服务端:根目录、拒绝规则、任务 允许列表和审计都由操作员配置,仓库内容无法扩大其权限。即使提示词处理流程被入侵或绕过,也无法调用不存在的工具。

快速开始

需要 Node ≥ 20,以及供 git_* 工具使用的 git 和用于 内容搜索的 ripgrep(rg)。从克隆的仓库构建需要 pnpm(corepack enable)。

npm install -g local-workspace-mcp          # puts workspace-mcp on PATH

# or from a clone:
pnpm install && pnpm build && npm link

workspace-mcp init-config     # writes ~/.config/local-workspace-mcp/config.json (mode 600)

# REQUIRED: replace the example workspace path with a real absolute path —
# any editor works; doctor fails until you do
nano ~/.config/local-workspace-mcp/config.json

workspace-mcp doctor          # must print "doctor: ALL GREEN" (use --json for CI)

生成的配置附带一个名为 example 的占位工作区 — 请将其替换为实际根目录,否则 doctor 会报告 root.example FAIL。 健康运行结束时会显示:

PASS policy.selftest — 9/9 cases correct
PASS mcp.startup — tool registration ok
doctor: ALL GREEN

最简可用配置(严格 JSON — 不支持注释或尾随逗号):

{
  "version": 1,
  "workspaces": {
    "myproj": { "path": "/absolute/path/to/repo", "tasks": [] }
  },
  "tasks": {},
  "deny": []
}

然后向宿主注册该服务。Claude Code 的配置如下:

claude mcp add local-workspace --scope user -- workspace-mcp serve --stdio
claude mcp list        # confirm it registered

其他宿主使用配置文件条目(见下文 — 将其替换为 which workspace-mcp 输出的绝对路径)。然后询问:“先使用 workspace_roots,再 对 myproj 执行 fs_list。” 首个有用的调用顺序:fs_list → git_status → 对未提交的工作执行 git_diff;否则,聊天客户端无法看到这些内容。

使用示例

# what the assistant can ask for
workspace_roots                        # authorized workspace ids, no host paths
fs_list   {workspace:"myproj"}
fs_read   {workspace:"myproj", path:"src/index.ts", startLine:1, maxLines:120}
fs_search_content {workspace:"myproj", query:"TODO"}        # literal; regex:true for rg syntax
git_status {workspace:"myproj"}        # branch, HEAD, uncommitted truth
git_diff  {workspace:"myproj"}         # worktree diff, bounded output
git_show  {workspace:"myproj", spec:"HEAD"}
task_list {workspace:"myproj"}
task_run  {workspace:"myproj", taskId:"typecheck"}

拒绝行为会明确说明,绝不会悄无声息:

fs_read {workspace:"myproj", path:".env"}              → ACCESS_DENIED  (or NOT_FOUND if absent)
fs_read {workspace:"myproj", path:"../../outside-root.txt"} → OUTSIDE_ROOT
task_run {workspace:"myproj", taskId:"nuke"}           → TASK_DENIED    (valid id, not enabled)
task_run {workspace:"myproj", taskId:"rm -rf /"}       → INVALID_ARGUMENT (malformed task id)
git_show {workspace:"myproj", spec:"--exec"}           → INVALID_ARGUMENT

拒绝代码表示策略按预期运行,并非需要报告的错误; 只有在操作员配置中才能扩大访问权限。任务/搜索超时 和输出限制会在正常结果中返回 timedOut:true/truncated:true,而非错误。INTERNAL_ERROR 涵盖进程启动/工具故障,在正常使用中不应出现;非 Git 根目录上的 git_* 会正常返回 {repo:false}。

工具概览

全部 23 个工具,并在 readOnlyHint 为 true 时标注(主机可自动批准纯读取操作)。task_run 是唯一有副作用的工具。

工具范围说明
fs_inspect单个文件通过 magic byte 检测类型(image/zip/ooxml/pdf/text/binary)、尺寸、sha256、openWith 提示
fs_image单张图片原生 MCP image 块(默认使用原始字节;披露 frame/fitMaxDim/format 转换);扫描 svg 后再栅格化
fs_contact_sheet≤24 张图片带标签的拼图;逐项授权检查与失败提示单元格;限制输出大小
fs_archive_list单个 zip成员表(大小、压缩率、加密状态、拒绝/不安全标记);分页且限制条目数
fs_archive_entry单个成员图片 → 原生块,文本 → 限长文本,其他 → 拒绝;路径遍历/符号链接/嵌套成员均会安全失败
fs_pdf_info单个 pdf页数、文本层是否存在(PDFium/WASM)
fs_pdf_page≤4 个 pdf 页面将页面渲染为原生图片块;限制像素数
fs_pdf_text≤50 个 pdf 页面限长文本提取;如实报告仅含图片的页面
fs_office_text单个 ooxmldocx 段落 / pptx 幻灯片 / xlsx 单元格;标记宏但绝不执行;拒绝旧版 OLE
workspace_roots读取配置工作区 id + 可用性;绝不返回主机路径
fs_list单个目录限制结果数、分页;按类别标记被拒绝的条目
fs_stat单个路径元数据;披露符号链接解析结果
fs_read单个文件按行范围读取、限制字节数;拒绝二进制文件
fs_read_many批量每个文件的内联错误信息、总量限制
fs_search_files文件名glob;存在仓库时使用 git 文件集合(遵循仓库顶层的 .gitignore);否则执行有限制的目录遍历
fs_search_content文件内容ripgrep --json;字面匹配或 regex:true;限制时间和结果数
git_status仓库分支、HEAD、已暂存/已修改/已删除/已重命名/未跟踪
git_diff仓库工作树/暂存区/ref 差异;限制结果;对被拒绝的路径进行脱敏
git_log仓库≤100 次提交
git_show仓库提交/标签和 ref:path 数据块;严格验证 ref
git_branches仓库分支、上游、工作树(对主机路径进行脱敏)
task_list配置每个工作区启用的任务 id
task_run子进程仅允许列表中的 argv;shell:false;限制时间/输出

支持的宿主

宿主机制状态
Claude Codeclaude mcp add local-workspace --scope user -- workspace-mcp serve --stdio;使用 claude mcp list 确认已验证
Claude Desktop在 claude_desktop_config.json 中添加 mcpServers 条目;重启应用已配置
Codex CLI在 ~/.codex/config.toml 中添加 mcp_servers stdio 条目支持
ChatGPT / Responses APIOpenAI Secure MCP Tunnel(openai/tunnel-client,仅出站);请参阅此表下方的隧道说明和云端披露ChatGPT 图像已验证;Responses 未测试
MCP Inspectorscripts/inspector-smoke.sh 测试套件,共 17 项检查已验证

GUI 宿主(尤其是 Claude Desktop)启动服务时使用的 PATH 通常很精简, 与 shell 中的不同。如果宿主报告 ENOENT,或在 doctor 状态正常时仍 保持断开,则说明二进制文件不在宿主的 PATH 中。请使用绝对路径 (which workspace-mcp)作为命令,并检查宿主的 MCP 日志。

Claude Desktop(macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "local-workspace": {
      "command": "/absolute/path/to/workspace-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Codex CLI(~/.codex/config.toml,或使用 codex mcp add):

[mcp_servers.local-workspace]
command = "/absolute/path/to/workspace-mcp"
args = ["serve", "--stdio"]

ChatGPT / Responses API 使用 OpenAI Secure MCP Tunnel:tunnel-client 会轮询出站 HTTPS 路径,并在本地启动 stdio 命令;不会开放入站网络 监听器(tunnel-client 可选绑定仅限 loopback 的健康检查端点——请参阅 docs/OPERATIONS.md)。

涉及三个值——请勿混淆(OpenAI 自己的文档提醒,这些值常被混为一谈):tunnel_… 是标识符,不是密钥;Runtime API key 是守护进程唯一需要的密钥(其 env: 名称为 CONTROL_PLANE_API_KEY);只有通过 CLI 创建或管理隧道时才需要 Admin API key——此处不需要。

# 1. Install tunnel-client (github.com/openai/tunnel-client).
# 2. In the OpenAI platform console, create a tunnel and a Runtime API key
#    (Tunnels permission: Read+Use to run/select one, Read+Manage to create):
#      https://platform.openai.com/settings/organization/tunnels
#      https://platform.openai.com/settings/organization/api-keys
# 3. Store the key where the daemon can read it unattended. On macOS, put it
#    in the login keychain and materialize a 0600 file the profile will
#    reference via `file:` (scripts/launchd/install.sh does both steps
#    against this exact location; on other platforms write the file
#    directly). Never put the raw key in the profile YAML, a plist, or on a
#    command line.
security add-generic-password -s tunnel-client-control-plane -a "$USER" -w
mkdir -p "$HOME/Library/Application Support/tunnel-client/secrets"
chmod 700 "$HOME/Library/Application Support/tunnel-client/secrets"
security find-generic-password -s tunnel-client-control-plane -a "$USER" -w \
  > "$HOME/Library/Application Support/tunnel-client/secrets/control-plane-api-key"
chmod 600 "$HOME/Library/Application Support/tunnel-client/secrets/control-plane-api-key"
# 4. Write the profile, validate it, and start the managed runtime
#    (attach to the existing tunnel id — no admin key needed):
tunnel-client init --profile local-workspace \
  --tunnel-id <tunnel_…> \
  --mcp-command "$(command -v workspace-mcp) serve --stdio" \
  --control-plane-api-key-ref file:"$HOME/Library/Application Support/tunnel-client/secrets/control-plane-api-key"
tunnel-client doctor --profile local-workspace --explain
tunnel-client runtimes connect --alias local-workspace \
  --profile local-workspace --tunnel-id <tunnel_…> \
  --runtime-api-key file:"$HOME/Library/Application Support/tunnel-client/secrets/control-plane-api-key"
tunnel-client runtimes status local-workspace --json
#    expect process_running=true, healthy=true, ready=true
# 5. In ChatGPT: https://chatgpt.com/#settings/Connectors → add connector →
#    Connection: Tunnel → select the tunnel (or paste its id) while the
#    daemon is running. A tunnel created in Platform does not appear in
#    ChatGPT until you bind a connector to it here.

macOS 持久运行:scripts/launchd/install.sh 会安装一个按用户运行的 LaunchAgent,使受管运行时在重启、登录、应用重启、进程退出、网络中断以及睡眠/唤醒后持续运行——无需手动重启。它需要使用第 3 步中的钥匙串项目 (tunnel-client-control-plane,账户 $USER),并会自行生成 权限为 0600 的文件。PATH 中需要有 jq。请参阅 docs/OPERATIONS.md §持久运行。 运维手册:docs/OPERATIONS.md。

ChatGPT 宿主验证(2026-10-11):刷新连接器后,实时连接发现了全部 23 个工具,并接收了原生 fs_image 图像 块。系统仅根据其像素描述了合成视觉金丝雀,不依赖文件元数据。PDF 和 Office 工具虽已公布,但尚未测试 ChatGPT 端各自的提取/渲染路径。未来 工具架构更新可能需要再次手动刷新连接器;每个图像工具也会返回元数据,以供无法呈现视觉内容的宿主使用。

云端披露:通过 ChatGPT 隧道路由时,工具输出(包括 图像字节和提取的文档文本)会经由 OpenAI 的连接器基础设施传输,以便模型获取。这正是该集成的用途, 但也意味着边界允许模型读取的任何内容都会离开本机,传输到该宿主。为提供给云端连接器的任何 工作区设置严格的根目录和拒绝规则。

权限模型

  • 根目录是显式指定的。 文件系统工具无法读取 workspaces[].path 之外的任何内容; ~、控制字符、Windows 驱动器路径和 .. 遍历会在任何系统调用之前被拒绝, 并在 realpath 之后再次检查。(允许列表中的 task_run 命令是唯一例外——它们会以你的身份在根目录之外运行,因此只允许 列入你自己愿意运行的命令。)将根目录指向你实际工作的项目;切勿授权 ~/ 或包含助手不应读取内容的父目录。
  • 默认拒绝, 包括:.env*/*.env 形式(.env[.*].{example,sample,template} 除外)、.envrc、私钥文件名、 .pem/.key/.p12/.pfx/.jks/.kdbx、.ssh、.aws、.azure、.gnupg、 .kube/kubeconfig、.docker、.npmrc、.netrc、.pgpass、.pypirc、 .git-credentials/.gitconfig、Shell 历史记录、*.tfvars、 secrets.{json,yaml,yml,toml}/.secrets/secrets.d、 credentials/service-account*.json/gha-creds-*.json,以及所有 .git 内部内容。这只是代表性列表——权威规则位于仓库中的 src/policy.ts 的 DEFAULT_DENY;拒绝策略采用失败关闭。
  • 文件名并非唯一边界: 即使文件名无害,只要文件中包含 BEGIN … PRIVATE KEY 装甲文本,也会在读取、git_show blob 和搜索预览中被拒绝。 扫描属于启发式纵深防御(威胁模型中说明了编码和大小预算限制);文件名/策略拒绝才是主要边界。
  • Git 只读且经过加固: 仅使用 argv 启动进程、--end-of-options、 严格的 ref 验证、字面路径规范,以及 GIT_TERMINAL_PROMPT=0。 在允许列表中的任务中,通过 GIT_CONFIG_* 覆盖固定主要仓库配置的执行键 (core.fsmonitor、core.sshCommand、 diff.external、core.hooksPath;每个驱动程序的 diff.<name>/filter.<name> 钩子是已记录的残余风险)。重命名差异和合并冲突中的 diff --cc 块,会针对其中提及的每个路径进行策略检查。
  • 任务通过声明指定,而非手动输入: 配置中的 argv 数组、shell:false、 经清理的环境变量、每项任务的超时和输出上限。操作员环境变量无法注入 GIT_*、 加载器或解释器钩子。
  • 错误信息长度受限: 每个错误都采用 CODE: message 格式;服务器生成的工具错误会隐藏绝对主机路径,但任务启动失败时会报告操作员配置的 argv 本身。 task_run 会返回子进程的 stdout/stderr,并将任务配置的 cwd 和工作区根目录字符串替换为 <root>——命令打印的其他绝对 路径不会被隐藏;这些输出来自操作员允许列表中的命令。

错误:ACCESS_DENIED、OUTSIDE_ROOT、NOT_FOUND、BINARY_FILE、 RESOURCE_LIMIT、TASK_DENIED、UNKNOWN_WORKSPACE、UNSUPPORTED_FORMAT、 WORKSPACE_UNAVAILABLE、INVALID_ARGUMENT、INTERNAL_ERROR,以及 配置加载/启动时的 CONFIG_ERROR。task_run 和搜索超时会在结果中返回 timedOut:true;媒体处理期限耗尽时,会在失败的项目或调用上报告 TIMEOUT:,因此多项目结果可能部分返回,而非整体失败。 Git 命令失败会显示为 INVALID_ARGUMENT(git_diff/git_log/git_show 会将非零退出状态映射为此错误, 包括超时导致的终止)或 INTERNAL_ERROR(git_status);仓库检测超时时会显示 repo:false,而 git_branches 会容忍非零退出状态并返回空列表。

它不会做什么

不会写入、编辑、删除、重命名或创建文件。不会运行 Shell。不会执行 git 变更操作(commit、push、clean 等)。不会启动网络监听器。不会使用仓库控制的配置。任务只会执行操作员预先声明的内容,而且这些任务仍会以你的用户身份运行,并产生实际副作用,因此请严格限制允许列表,并优先选择只读命令。

安全架构

端口与适配器、单一实现、单一传输:

AI host ── stdio JSON-RPC ──▶ workspace-mcp serve --stdio

  config.ts   trust root: operator config (keep it outside watched roots)
  paths.ts    lexical + realpath containment, bounded error mapping
  policy.ts   default-deny rules + validated operator globs
  fsOps.ts    bounded reads/searches (ripgrep --json, structured parsing)
  git.ts      read-only git, strict refs, diff redaction, object-type gates
  tasks.ts    allowlisted argv only, process-group timeouts
  exec.ts     sanitized + git-hardened subprocess environments
  audit.ts    metadata-only JSONL; refuses symlinked targets

完整的边界分析、多轮发现记录、对抗性回归测试套件以及已记录的剩余风险,详见 docs/THREAT-MODEL.md。披露政策见 SECURITY.md。

配置参考

~/.config/local-workspace-mcp/config.json;若文件或其目录允许组用户或所有用户写入,或路径是符号链接,则加载时会拒绝。

// annotated for reading — the parser is strict JSON;
// this block is documentation, not a template. Start from `init-config`
// output, or strip the // comments (the JSON itself is otherwise valid).
{
  "version": 1,
  "workspaces": {
    "myproj": {
      "path": "/abs/path", // required
      "description": "…",
      "tasks": ["typecheck"], // ids the caller may run here
    },
  },
  "tasks": {
    "typecheck": {
      "command": ["pnpm", "typecheck"], // argv only; never a command string
      "cwd": "subdir-inside-root", // optional; contained to the root
      "timeoutMs": 180000, // 1s..300s; 300s is a hard cap
      "env": { "PATH": "/opt/node/bin:${PATH}" }, // ${VAR} expands vs base env
    },
  },
  "deny": ["**/extra-secret/**"], // appended to built-in rules; evaluated
  // BEFORE the template allowlist, so an operator can re-deny
  // .env.example; malformed patterns fail config load, fail-closed
  "auditLog": "/abs/path.jsonl", // optional; defaults next to the config
  "limits": {}, // byte/line/count caps
}

常用的 limits 键(键:默认值):maxReadFileBytes:读取时的文件大小上限为 5 MB,defaultReadBytes:每次读取 64 KiB,maxSearchResults:200,searchDeadlineMs:20 s,gitTimeoutMs:15 s,maxTaskOutputBytes:64 KiB,walkEntryCap/walkDepthCap:50k 个条目 / 深度 20。完整的带范围限制的架构见仓库中的 src/config.ts。调用方可向 task_run 传入 timeoutMs,以缩短任务超时时间;该值不能超过配置值或 300 s 的硬上限。

覆盖项:WORKSPACE_MCP_CONFIG(配置文件)、WORKSPACE_MCP_CONFIG_DIR(配置目录和审计日志位置)、workspace-mcp serve --config <path>(CLI 标志)。init-config 不会覆盖现有配置;如需重置,请先删除该文件。

故障排查

症状处理方法
npm install -g 因 EACCES 失败设置用户级前缀(npm config set prefix ~/.local,并将 ~/.local/bin 添加到 PATH),或使用由 nvm 管理的 Node;切勿使用 sudo npm -g
安装后提示 command not found可执行文件位于 $(npm prefix -g)/bin;将其添加到 PATH,或使用克隆仓库 + npm link 的方式
主机显示已断开连接运行 workspace-mcp doctor,修复第一个 FAIL;如果结果为绿色,则说明主机的 spawn PATH 不同——请使用可执行文件的绝对路径
启动时出现 CONFIG_ERROR权限、JSON、符号链接或未知任务问题;消息会指出原因
init-config 以状态码 1 退出它不会覆盖现有配置;请先删除现有配置
WORKSPACE_UNAVAILABLE根路径已移动或删除;修复或移除工作区条目
TASK_DENIED该工作区未启用此任务 ID;task_list 会显示允许列表
找不到任务可执行文件doctor 会标记 task.<id>.executable;请安装它或修正任务的 env.PATH
搜索没有结果rg 必须位于经过清理的 PATH 中;doctor 会检查这一点
ACCESS_DENIED/OUTSIDE_ROOT/BINARY_FILE策略按预期工作;仅在操作员配置中放宽策略
媒体调用/条目出现 TIMEOUT:超出时限——缩小请求范围(减少页面/条目数量,降低 fitMaxDim),或提高 limits.mediaTimeoutMs
意外出现 INTERNAL_ERROR检查主机的 MCP stderr 日志;按照 SECURITY.md 中的说明报告
Tunnel(ChatGPT)已关闭运行 tunnel-client runtimes status;恢复方法见 docs/OPERATIONS.md
已创建 Tunnel,但无法在 ChatGPT 中选择检查你的主体是否拥有 Tunnels Read+Use 权限,并等待权限传播;Platform 中的 Tunnel 不会自动显示在 ChatGPT 中
重启/登录后 Tunnel 消失scripts/launchd/install.sh 会安装自动恢复的 LaunchAgent;参见 docs/OPERATIONS.md §Persistence

workspace-mcp doctor --json 可为 CI 或包装脚本提供机器可读的输出。要彻底重置:删除配置和 ~/.config/local-workspace-mcp/audit.jsonl,然后重新运行 init-config。要 彻底卸载,还需移除主机条目(claude mcp remove、mcpServers/mcp_servers 块或 Tunnel 配置文件),并运行 npm uninstall -g local-workspace-mcp(若通过克隆仓库链接,则运行 npm unlink)。

兼容性

  • Node ≥ 20(使用 node:util parseArgs;已在 Node 20.11、22.12 和 24.21 上验证打包安装)。
  • 仅支持 macOS/Linux — 通过 package.json 中的 os 声明,并由 doctor(platform)检查。Windows 不受支持,而非仅未经测试:任务超时依赖 POSIX 进程组终止,git/任务隔离固定使用 /dev/null。
  • MCP SDK @modelcontextprotocol/sdk v1.x 系列(规范 ≤ 2025-11-25);暂未采用 v2 API(参见 docs/RESEARCH.md)。
  • fs_search_content 需要 ripgrep;git_* 需要 git。

验证构建

pnpm install --frozen-lockfile
pnpm test                    # 275 vitest cases incl. adversarial + red-team regressions
pnpm typecheck && pnpm build
workspace-mcp doctor         # deterministic diagnostics
scripts/inspector-smoke.sh <workspace-id>   # 17-check MCP Inspector battery
pnpm audit --prod            # dependency audit

贡献、安全与许可

  • CONTRIBUTING.md:先写 RED 测试、失败时关闭,以及未经设计评审不得扩展能力范围。
  • SECURITY.md:漏洞报告与范围。
  • CHANGELOG.md:按发现/版本编写的发布说明。
  • 许可证:MIT。

发布状态

版本 0.2.0 已作为 local-workspace-mcp 发布到 npm(SLSA 来源证明、OIDC 可信发布),并以 io.github.peter4leadson/local-workspace-mcp — latest 列入官方 MCP Registry。请参阅 CHANGELOG.md 了解发布历史。 仓库中维护着 0.2.0 发布决策记录 docs/RELEASE-0.2.0-DECISION.md(内部记录 — 不随 tarball 发布;冻结的 0.1.0 记录为 docs/RELEASE-PACKET.md)。


由 Peter C. Bennett 维护。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。