agent-workspace-mcp

リポジトリ探索、コードインテリジェンス、WebワークスペースのコンテキストのためのTypeScript対応MCPサーバー。

English | 简体中文

English

agent-workspace-mcp は、完全なIDE統合を必要とせずに、ローカルコードベースに対してTypeScriptを認識したプロジェクトコンテキストを提供するローカル stdio MCPサーバーです。これは単純なファイル検索と重量級のエディタツールの間に位置し、MCPクライアントが明確なプロジェクト境界を持つリポジトリを読み取るのを支援します。

このサーバーは、焦点を絞った一連のツールを公開します。get_diagnostics はファイルのTypeScript構文およびセマンティック診断を返します。get_definition、get_references、get_symbol_summary は、1から始まるソース位置に基づいてコードナビゲーションとシンボルの洞察を提供します。discover_repository_structure は、ワークスペース内のパッケージ、ワークスペースファイル、tsconfig ファイルをスキャンします。get_web_project_context は、エントリーポイント、ルーティングサーフェス、設定ファイル、フレームワークのヒントなどのフロントエンド指向のコンテキストを追加します。reload_project は、キャッシュされたTypeScriptの状態をクリアし、プロジェクトメタデータを更新します。

これは特に、モノレポ、フロントエンドアプリケーション、および「どのパッケージを調査すべきか」「このシンボルはどこで定義されているか」「このリポジトリはWebアプリのように見えるか」といった質問に対して信頼できる回答が必要なローカルリポジトリのワークフローにおいて非常に役立ちます。

クイックスタート

npx で直接実行します：

npx -y agent-workspace-mcp@0.1.4

~/.codex/config.toml を手動で編集せずにCodexを自動設定するには：

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で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。