agent-workspace-mcp

TypeScript-fähiger MCP-Server für Repository-Erkennung, Code-Intelligenz und Web-Workspace-Kontext.

Englisch | 简体中文

Englisch

agent-workspace-mcp ist ein lokaler stdio MCP-Server, der TypeScript-fähigen Projektkontext für lokale Codebasen bereitstellt, ohne eine vollständige IDE-Integration zu erfordern. Er fungiert als Bindeglied zwischen einfacher Dateisuche und schwergewichtigen Editor-Tools und hilft MCP-Clients dabei, Repositories mit expliziten Projektgrenzen zu lesen.

Er stellt eine fokussierte Reihe von Tools bereit. get_diagnostics gibt TypeScript-syntaktische und semantische Diagnosen für eine Datei zurück. get_definition, get_references und get_symbol_summary bieten Codenavigation und Symboleinsichten basierend auf 1-basierten Quellpositionen. discover_repository_structure durchsucht einen Workspace nach Paketen, Workspace-Dateien und tsconfig-Dateien. get_web_project_context fügt Frontend-orientierten Kontext wie Einstiegspunkte, Routing-Oberflächen, Konfigurationsdateien und Framework-Hinweise hinzu. reload_project löscht den zwischengespeicherten TypeScript-Status und aktualisiert die Projektmetadaten.

Er ist besonders nützlich für Monorepos, Frontend-Anwendungen und lokale Repository-Workflows, bei denen Sie zuverlässige Antworten auf Fragen benötigen wie: „Welches Paket sollte ich untersuchen?“, „Wo ist dieses Symbol definiert?“ oder „Sieht dieses Repository wie eine Web-App aus?“.

Schnellstart

Direkt mit npx ausführen:

npx -y agent-workspace-mcp@0.1.4

Um Codex automatisch zu konfigurieren, ohne ~/.codex/config.toml manuell zu bearbeiten:

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

Um die installierte Paketversion auszugeben:

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

Oder global installieren:

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

MCP-Client-Konfiguration

Für Codex fügen Sie dies zu ~/.codex/config.toml hinzu:

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

Wenn Ihr MCP-Client unter Windows Schwierigkeiten hat, npx zuverlässig aufzulösen, bevorzugen Sie:

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

Wenn Sie den oben genannten One-Shot-Setup-Befehl verwenden, schreibt das Paket diesen Eintrag automatisch für Sie und verwendet npx.cmd unter Windows.

Für MCP-Clients im JSON-Stil:

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

Wenn Sie einen lokalen Checkout anstelle von npx bevorzugen:

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

Der Server schlägt bei ungültiger Eingabe sofort fehl, verwendet Heuristiken für Dateisystem- und Paketmetadaten zur Repository-Klassifizierung und hält den TypeScript-Sprachdienststatus im Arbeitsspeicher, sodass wiederholte Aufrufe nach dem ersten Laden wesentlich schneller sind.

Details zur Entwicklung und Mitwirkung finden Sie unter CONTRIBUTING.md. Informationen zur Meldung von Sicherheitslücken finden Sie unter SECURITY.md. Lizenzbedingungen finden Sie unter 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。