agent-workspace-mcp

저장소 탐색, 코드 인텔리전스 및 웹 워크스페이스 컨텍스트를 위한 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 상태를 지우고 프로젝트 메타데이터를 새로 고칩니다.

이 도구는 "어떤 패키지를 검사해야 하는지", "이 심볼은 어디에 정의되어 있는지", 또는 "이 저장소가 웹 앱처럼 보이는지"와 같은 질문에 신뢰할 수 있는 답변이 필요한 모노레포, 프론트엔드 애플리케이션 및 로컬 저장소 워크플로우에 특히 유용합니다.

빠른 시작

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。