agent-workspace-mcp

支持 TypeScript 的 MCP 服务器，用于仓库发现、代码智能和 Web 工作区上下文。

English | 简体中文

English

agent-workspace-mcp 是一个本地 stdio MCP 服务器，它在无需完整 IDE 集成的情况下，为本地代码库提供 TypeScript 感知的项目上下文。它介于原始文件搜索和重量级编辑器工具之间，帮助 MCP 客户端通过明确的项目边界来读取代码仓库。

它公开了一组专注的工具。get_diagnostics 返回文件的 TypeScript 语法和语义诊断。get_definition、get_references 和 get_symbol_summary 提供基于 1-based 源位置的代码导航和符号洞察。discover_repository_structure 扫描工作区中的包、工作区文件和 tsconfig 文件。get_web_project_context 添加面向前端的上下文，例如入口点、路由页面、配置文件和框架提示。reload_project 清除缓存的 TypeScript 状态并刷新项目元数据。

它对于 Monorepo、前端应用程序和本地仓库工作流特别有用，当你想要可靠地回答诸如“我应该检查哪个包”、“这个符号在哪里定义”或“这个仓库看起来像一个 Web 应用吗”之类的问题时，它非常有效。

Quick Start

直接使用 npx 运行：

npx -y agent-workspace-mcp@0.1.4

若要自动配置 Codex 而无需手动编辑 ~/.codex/config.toml：

npx -y agent-workspace-mcp@0.1.4 --setup-codex

打印已安装的包版本：

npx -y agent-workspace-mcp@0.1.4 --version

或者全局安装：

npm install -g agent-workspace-mcp
agent-workspace-mcp

MCP Client Configuration

对于 Codex，请将其添加到 ~/.codex/config.toml：

[mcp_servers.agent_workspace_mcp]
command = "npx"
args = ["-y", "agent-workspace-mcp"]

在 Windows 上，如果你的 MCP 客户端难以可靠地解析 npx，建议使用：

[mcp_servers.agent_workspace_mcp]
command = "npx.cmd"
args = ["-y", "agent-workspace-mcp"]

如果你使用上面的“一键”设置命令，该包会自动为你写入此条目，并在 Windows 上使用 npx.cmd。

对于 JSON 风格的 MCP 客户端：

{
  "mcpServers": {
    "agent-workspace-mcp": {
      "command": "npx",
      "args": ["-y", "agent-workspace-mcp"]
    }
  }
}

如果你更喜欢本地检出而不是 npx：

{
  "mcpServers": {
    "agent-workspace-mcp": {
      "command": "node",
      "args": ["C:/path/to/agent-workspace-mcp/dist/cli.js"]
    }
  }
}

该服务器对无效输入会快速失败，使用文件系统和包元数据启发式进行仓库分类，并将 TypeScript 语言服务状态保留在内存中，因此在初始加载后重复调用会快得多。

有关开发和贡献的详细信息，请参阅 CONTRIBUTING.md。有关漏洞报告，请参阅 SECURITY.md。许可条款位于 LICENSE 中。

简体中文

agent-workspace-mcp 是一个本地 stdio MCP Server，用于在不依赖完整 IDE 集成的前提下，为本地代码仓库提供 TypeScript 感知的项目上下文。它介于简单文件搜索和重量级编辑器工具之间，适合为各类 MCP Client 提供更稳定的仓库级理解能力。

它提供一组收敛的工具能力。get_diagnostics 用于返回单文件的 TypeScript 语法和语义诊断；get_definition、get_references、get_symbol_summary 用于基于 1-based 行列号做定义跳转、引用查找和符号摘要；discover_repository_structure 用于扫描 workspace、package 和 tsconfig 结构；get_web_project_context 用于补充前端语境，比如入口文件、路由面、配置文件和框架线索；reload_project 用于清空缓存并重新加载 TypeScript 项目状态。

这个项目尤其适合 monorepo、前端应用和本地仓库分析场景。比如你想先判断应该查看哪个 package、某个符号真正定义在哪里，或者当前仓库是否更像一个 web app。

快速开始

直接通过 npx 运行：

npx -y agent-workspace-mcp@0.1.4

如果你不想手动编辑 ~/.codex/config.toml，可以直接执行：

npx -y agent-workspace-mcp@0.1.4 --setup-codex

如果你想查看当前包版本：

npx -y agent-workspace-mcp@0.1.4 --version

或者全局安装：

npm install -g agent-workspace-mcp
agent-workspace-mcp

MCP 客户端配置

如果你在用 Codex，可在 ~/.codex/config.toml 中加入：

[mcp_servers.agent_workspace_mcp]
command = "npx"
args = ["-y", "agent-workspace-mcp"]

如果你使用上面的自动配置命令，包会帮你写入这段配置；在 Windows 上会自动改用 npx.cmd。

如果你使用通用 JSON 风格的 MCP 配置：

{
  "mcpServers": {
    "agent-workspace-mcp": {
      "command": "npx",
      "args": ["-y", "agent-workspace-mcp"]
    }
  }
}

如果你希望直接从本地构建产物启动：

{
  "mcpServers": {
    "agent-workspace-mcp": {
      "command": "node",
      "args": ["C:/path/to/agent-workspace-mcp/dist/cli.js"]
    }
  }
}

这个服务对非法输入会直接失败，仓库和 Web 项目识别主要依赖文件系统与包元数据启发式，并且会在进程内缓存 TypeScript Language Service，所以首次加载后，后续调用会快很多。

如果你想参与开发或贡献代码，见 CONTRIBUTING.md；安全问题处理方式见 SECURITY.md；许可证见 LICENSE。