비공식 — 개인 프로젝트이며, Relace와는 관련이 없습니다.
AI로 구축됨 — 전적으로 AI 지원(Antigravity, Codex, Cursor, Github Copilot, Windsurf)을 받아 개발되었습니다.
AI 기반 코드 편집 및 지능형 코드베이스 탐색 도구를 제공하는 MCP 서버입니다.
이전 |
|
수동 grep, 관련 파일 누락 | 자연어로 질문하여 정확한 위치 파악 |
편집 시 다른 곳의 import 깨짐 | import 및 호출 체인 추적 |
전체 재작성으로 토큰 소모 | 변경 사항 설명, 줄 번호 불필요 |
줄 번호 오류로 코드 손상 | 10,000+ 토큰/초 병합 |
Fast Apply — Relace API를 통해 10,000+ 토큰/초의 속도로 코드 편집 적용
Agentic Search — 자연어 쿼리를 통한 에이전트형 코드베이스 탐색
Agentic Retrieval — 하이브리드 의미론적 힌트 + 실시간 코드 탐색, 오래된 힌트 지원 및 명시적 클라우드 유지 관리 (MCP_SEARCH_RETRIEVAL=1로 활성화; MCP_RETRIEVAL_BACKEND로 백엔드 선택)
Cloud Search — 클라우드 동기화 저장소에 대한 의미론적 코드 검색
Related MCP server: code-context
relace 백엔드(기본값) 사용: Relace 대시보드에서 API 키를 가져온 후 MCP 클라이언트에 추가하세요:
~/.cursor/mcp.json
{
"mcpServers": {
"relace": {
"command": "uv",
"args": ["tool", "run", "relace-mcp"],
"env": {
"RELACE_API_KEY": "rlc-your-api-key",
"MCP_BASE_DIR": "/absolute/path/to/your/project"
}
}
}
}claude mcp add relace \
--env RELACE_API_KEY=rlc-your-api-key \
--env MCP_BASE_DIR=/absolute/path/to/your/project \
-- uv tool run relace-mcp~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"relace": {
"command": "uv",
"args": ["tool", "run", "relace-mcp"],
"env": {
"RELACE_API_KEY": "rlc-your-api-key",
"MCP_BASE_DIR": "/absolute/path/to/your/project"
}
}
}
}.vscode/mcp.json
{
"mcp": {
"servers": {
"relace": {
"type": "stdio",
"command": "uv",
"args": ["tool", "run", "relace-mcp"],
"env": {
"RELACE_API_KEY": "rlc-your-api-key",
"MCP_BASE_DIR": "${workspaceFolder}"
}
}
}
}
}~/.codex/config.toml
[mcp_servers.relace]
command = "uv"
args = ["tool", "run", "relace-mcp"]
[mcp_servers.relace.env]
RELACE_API_KEY = "rlc-your-api-key"
MCP_BASE_DIR = "/absolute/path/to/your/project"변수 | 필수 | 설명 |
| ✅* | Relace 대시보드의 API 키; Relace 제공자 및 클라우드 도구에 필수 |
| ❌ |
|
| ❌ | 의미론적 검색 백엔드: |
| ❌ | 검색 힌트 정책: |
| ❌ | 로컬 인덱스에 대한 주기적 새로고침 모니터링 활성화; 고정된 |
| ❌ | 로컬 인덱스 모니터링 주기(초) (기본값: |
| ❌ | 첫 번째 로컬 인덱스 확인 전 초기 지연 시간(초) (기본값: |
| ❌ | 턴 상태 사용자 메시지 정책: |
| ❌ | 검색 중 |
| ❌ | LSP 지원 검색 활성화: |
| ❌ | 프로젝트 루트 재정의 (MCP Roots → Git → 작업 공간 저장소 → CWD를 통해 자동 감지) |
| ❌ | 파일 로깅: |
| ❌ | 중앙 집중식 설정을 위한 |
* 다음 두 가지 조건이 모두 충족될 경우 선택 사항: (1) APPLY_PROVIDER 및 SEARCH_PROVIDER가 Relace가 아닌 제공자일 경우, (2) MCP_RETRIEVAL_BACKEND가 codanna, chunkhound, 또는 none일 경우.
.env 사용법, 인코딩 설정, 사용자 지정 LLM 제공자 등에 대한 자세한 내용은 docs/advanced.md를 참조하세요.
항상 사용 가능: fast_apply, agentic_search. agentic_retrieval은 MCP_SEARCH_RETRIEVAL=1이 필요합니다. 클라우드 도구는 MCP_RETRIEVAL_BACKEND=relace일 때만 사용 가능합니다. index_status는 relace, codanna, chunkhound에서 사용 가능하며 MCP_RETRIEVAL_BACKEND=none일 때는 숨겨집니다.
MCP 기본 검색 인터페이스 사용: 도구는 list_tools(), 리소스는 list_resources()를 사용하세요.
자세한 매개변수는 docs/tools.md를 참조하세요.
LSP 도구는 시스템에 설치된 외부 언어 서버를 사용합니다.
언어 | 언어 서버 | 설치 명령어 |
Python | basedpyright | (번들 포함) |
TypeScript/JS | typescript-language-server |
|
Go | gopls |
|
Rust | rust-analyzer |
|
작업 모니터링을 위한 실시간 터미널 UI.
pip install relace-mcp[tools]
relogs자세한 사용법은 docs/dashboard.md를 참조하세요.
Loc-Bench 코드 로컬라이제이션 데이터셋을 사용하여 agentic_search 성능을 평가합니다.
git clone https://github.com/possible055/relace-mcp.git
cd relace-mcp
uv sync --extra benchmark
# Build dataset from Hugging Face
uv run --extra benchmark python -m benchmark.cli.build_locbench --output artifacts/data/raw/locbench_v1.jsonl
# Run evaluation
uv run --extra benchmark python -m benchmark.cli.run --dataset artifacts/data/raw/locbench_v1.jsonl --limit 20모든 벤치마크 아티팩트는 benchmark/.data/ 아래에 기록됩니다.
그리드 검색, 분석 도구 및 지표 해석에 대해서는 docs/benchmark.md를 참조하세요.
플랫폼 | 상태 | 참고 |
Linux | ✅ 완벽 지원 | 기본 개발 플랫폼 |
macOS | ✅ 완벽 지원 | 모든 기능 사용 가능 |
Windows | ⚠️ 부분 지원 |
|
오류 또는 메시지 | 해결 방법 |
| Relace 제공자나 클라우드 도구 사용 시 |
| 대상 블록 근처에 1-3개의 고유한 앵커 라인 포함 |
| 경로가 존재하며 |
| 파일이 10MB를 초과함; 변경 사항을 더 작은 파일이나 편집으로 분할 |
| UTF-8이 아닌 프로젝트의 경우 |
| API 키 및 제공자 설정 확인 |
| 나중에 다시 시도하거나 요청 볼륨을 줄임 |
| 네트워크 액세스 확인 후 다시 시도 |
| 병합이 diff를 생성할 수 있도록 더 구체적인 앵커나 구체적인 새 라인 추가 |
| 자리 표시자 마커가 예상되는 리터럴 출력이 아닌 자리 표시자로만 사용되는지 확인 |
| 삭제가 많은 대규모 편집을 분할하거나 명시적인 제거 지시어 사용 |
| 변경 사항을 더 작고 국소적인 편집으로 분할 |
git clone https://github.com/possible055/relace-mcp.git
cd relace-mcp
uv sync --extra dev --extra benchmark
uv run pytest
uv run --extra dev --extra benchmark pytest benchmark/tests -qMIT
Search codebase for code locations matching a query.
Use when you know the name or structure you're looking for — function names, class names, modules, or how components connect. For conceptual/behavioral queries without known identifiers, use agentic_retrieval instead.
Returns file paths with line ranges and an explanation of findings. Keys: explanation (str), files (dict[path → {lines, snippet}]), turns_used (int).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to find. Prefer specific identifiers over vague concepts. ✅ 'UserService class' ✅ 'where is JWT validation done' ❌ 'error handling' (too vague — results will be poor) Natural language or exact symbol names both accepted. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, etc. The description adds that the tool returns file paths with line ranges and explanations, providing useful context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (5 sentences), front-loaded with purpose, then usage guidelines, then return format and keys. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, the description covers purpose, usage, return format, and is supplemented by annotations. With an output schema present, return details are adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter 'query' already has a detailed description with examples in the schema. The tool description adds minimal additional meaning, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search codebase for code locations matching a query.' It uses a specific verb ('search') and resource ('codebase'), and distinguishes from the sibling tool 'agentic_retrieval' by noting that this tool is for queries with known identifiers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (when you know the name or structure) and when not to (conceptual/behavioral queries), naming the alternative tool 'agentic_retrieval'. This provides clear guidance for the AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete cloud repository and local sync state. IRREVERSIBLE.
Removes all indexed data from Relace Cloud. Use cloud_list to find repo IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be True to proceed. | |
| repo_id | No | Optional repo ID to delete directly (use cloud_list to find). If not provided, deletes the repo associated with current directory. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as destructive (destructiveHint=true). The description adds detail: 'IRREVERSIBLE' and clarifies it removes both cloud data and local sync state, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a warning. All information is front-loaded with the core action, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (not shown), return values are handled. The description covers the destructive nature, local state removal, and the confirm parameter. Could mention confirmation step explicitly, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear param descriptions. The description adds no extra meaning to params beyond hinting repo_id can come from cloud_list, but does not elaborate on confirm param or provide additional syntactic details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a cloud repository and local sync state, with the verb 'delete' and specific resource. It distinguishes from siblings like cloud_list (for listing) and implies this is for removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using cloud_list to find repo IDs, providing helpful context. However, it does not explicitly state when to use this tool vs alternatives (e.g., cloud_sync) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[ADMIN] List all repositories in your Relace Cloud account.
Use to find repo_id for cloud_clear. Not needed for normal search/sync workflow. Returns repository IDs, names, and indexing status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint; description adds that it returns specific fields and is admin-only, complementing without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with [ADMIN], no fluff; every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has output schema for returns; description covers purpose, usage, and relationship to siblings; fully adequate for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist and schema coverage is 100%; description adds usage context (output fields) beyond schema, meeting baseline for zero-param case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists all repositories, with an admin prefix and explicit use case for cloud_clear, distinguishing from normal search/sync workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (find repo_id for cloud_clear) and when not needed (normal search/sync), providing clear differentiation from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for code by meaning using AI embeddings. Requires cloud_sync first.
Use for conceptual queries where you don't know the exact file, class, or function name. Prefer agentic_search when you know the exact identifier or symbol name.
Prerequisite: cloud_sync must have been run at least once. Fails if RELACE_API_KEY is not set or no sync state exists.
Returns: {results (list), result_count (int), warnings (list[str]), query (str), branch (str), repo_id (str)}. Check warnings[] for stale index alerts (e.g., uncommitted local changes).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language description of the code to find. ✅ 'function that validates JWT and returns user ID' ✅ 'rate limiting middleware for HTTP requests' ❌ 'auth' (too vague — low-relevance results) Be specific about behavior, not just topic. | |
| branch | No | Branch to search (null = API default branch). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already define read-only, idempotent, non-destructive behavior. Description adds failure modes (RELACE_API_KEY, sync state) and return structure with warnings for stale indices.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
8 sentences, all value-adding: purpose, prerequisite, usage guidance, failure conditions, return type, warning tip. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 2 params, annotations, and output schema, the description covers purpose, prerequisites, usage, failures, return shape, and warnings. Complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both parameters. The tool description does not add extra parameter information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for code by meaning using AI embeddings, distinguishing it from agentic_search for exact identifier searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (conceptual queries) and when to prefer agentic_search (exact identifiers). Also mentions prerequisite cloud_sync and failure conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload or refresh codebase to Relace Cloud for semantic search.
Check index_status() first—skip this if cloud freshness is already 'fresh'. Syncs git-tracked files to enable cloud_search. Incremental by default.
Advanced (Relace-specific): force=True Re-upload all files; use after large refactors. force=True+mirror=True Delete cloud files absent locally; use after branch switch.
Returns: {sync_mode (str), files_created (int), files_updated (int), files_deleted (int), files_unchanged (int), warnings (list[str]), repo_id (str), repo_head (str)}. Check warnings[] for truncation or suppressed deletes. Fails if not in a git repo or RELACE_API_KEY is not set.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Ignore cache, upload all files (default: false). | |
| mirror | No | With force=True, delete cloud files not in local (default: false). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Clearly discloses incremental default, idempotent nature (aligning with annotations), and potential destructive behavior of force+mirror, plus warnings about truncation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured in concise paragraphs with clear headings for advanced options, return format, and failure conditions—every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Thoroughly covers prerequisites, usage guidance, advanced options, return structure, and failure cases, leaving no gaps given the tool's complexity and existing annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant value beyond schema descriptions by explaining advanced use cases for force and mirror, including when to use each option.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb+resource ('Upload or refresh codebase to Relace Cloud for semantic search') and distinguishes from siblings by referencing index_status and cloud_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (after checking index_status), when to skip (if fresh), and provides advanced scenarios for force and mirror usage with concrete examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit or create a file using intelligent merging.
For new files: writes content directly. For existing files: merges edit_snippet with current content using anchor lines. Anchor lines are verbatim lines copied from the existing file that help locate the exact edit target. Include 1-2 unique lines adjacent to the change. Truncation markers are recommended for larger scoped edits but not required. Markdown files keep fenced code blocks verbatim; outer fence stripping is skipped for .md/.mdx targets.
On error, the response includes a code field:
NEEDS_MORE_CONTEXT: merge model could not locate the target - add 1-2 unique anchor lines from immediately around the edit location.
APPLY_NOOP: merge returned an identical file even though the snippet contained explicit remove directives or concrete new lines not present in the original.
BLAST_RADIUS_EXCEEDED: edit scope too large - split into smaller edits.
MARKER_LEAKAGE: placeholder marker text leaked into merged output (treated as literal text).
TRUNCATION_DETECTED: merged output shrank drastically and no explicit remove directive was provided.
On success: {status: "ok", diff: str | None (unified diff, None for new files or no-op)}.
Do NOT use this tool to delete files or clear file contents. Use a dedicated file management tool for those operations.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path (absolute or relative to MCP_BASE_DIR; if MCP_BASE_DIR is unset, relative paths resolve against MCP Roots). | |
| edit_snippet | Yes | Code snippet representing the changes. Include only the lines being added or modified, plus placeholder comments for unchanged parts when useful for larger scoped edits: `// ... existing code ...` (JS/TS), `# ... existing code ...` (Python/shell). Anchor the edit with 1-2 verbatim lines from the existing file. | |
| instruction | No | Optional natural language hint to disambiguate the target location (e.g., 'add after imports', 'inside the if block'). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, consistent with a mutating edit. The description adds far more: explains the merging behavior with anchor lines, truncation markers, markdown handling, and a full set of error codes with their meanings and remedies. It also documents the success response format. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal but well-structured: core purpose first, then merge details, then error codes, then a do-not-use note. Each sentence adds value. A slight trim could be made (e.g., the truncation markers sentence could be part of anchor lines), but overall it's efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (indicated by CONTEXT SIGNALS) and the input schema is fully described, this description is complete: it covers all behavioral aspects, error handling with codes, response format, and explicit exclusions. No gaps remain for an agent to misunderstand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for all three parameters. The description still adds substantial value: for 'path' it clarifies resolution relative to MCP_BASE_DIR or MCP Roots; for 'edit_snippet' it gives concrete examples of placeholder comments and anchor line usage; for 'instruction' it provides natural language examples. This goes well beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Edit or create a file using intelligent merging,' which is a specific verb+resource pair. The sibling tools are all cloud/agentic search or index utilities, so this tool is clearly distinct as a file editing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: for new files write directly, for existing files merge with anchors. It also provides a clear do-not-use instruction: 'Do NOT use this tool to delete files or clear file contents. Use a dedicated file management tool for those operations' – directly indicating when to avoid it and naming an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the single active indexing backend in read-only mode.
Use this before retrieval when you need to know whether the active backend is fresh and
whether semantic hints are usable. Returns active_backend, a single backend status
object with freshness and hints_usable, and background_monitor (state, reason).
This tool never refreshes indexes; if active_backend is relace and
backend.status.needs_sync is true, run cloud_sync().
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| trace_id | Yes | Trace ID for correlating logs for this tool call. |
| active_backend | Yes | The configured active indexing backend. |
| base_dir | No | Resolved repository base directory, if available. |
| base_dir_source | No | How the base directory was resolved, when resolution succeeded. |
| backend | No | Status summary for the active backend, when inspection succeeded. |
| background_monitor | No | Background monitor state summary, when inspection succeeded. |
| error | No | Error message explaining why status inspection failed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds key behavioral details: 'never refreshes indexes', conditions for needing cloud_sync, and outlines the return structure, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, and every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema, the description sufficiently explains the return fields (active_backend, background_monitor) and the condition for using a sibling tool. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (0 params, 100% coverage). The description adds no parameter info, which is appropriate as there are none. Baseline 4 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'inspect', the resource 'single active indexing backend', and the mode 'read-only'. It clearly defines what the tool does and distinguishes it from siblings like 'cloud_sync'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('before retrieval when you need to know whether the active backend is fresh and whether semantic hints are usable') and when not to ('never refreshes indexes') with an alternative ('run cloud_sync()').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.4agentic_searchcloud_clearcloud_listcloud_searchcloud_syncfast_apply4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / edit_snippet / descriptionAdded value: +"Code snippet representing the changes. Include only the lines being added or modified, plus placeholder comments for unchanged parts when useful for larger scoped edits: `// ... existing code ...` (JS/TS), `# ... existing code ...` (Python/shell). Anchor the edit with 1-2 verbatim lines from the existing file."Input schema / properties / instruction / descriptionAdded value: +"Optional natural language hint to disambiguate the target location (e.g., 'add after imports', 'inside the if block')."Input schema / properties / path / descriptionAdded value: +"File path (absolute or relative to MCP_BASE_DIR; if MCP_BASE_DIR is unset, relative paths resolve against MCP Roots)."fast_searchindex_statusv1.0.0cloud_clearcloud_infocloud_listcloud_searchcloud_synccloud_clearcloud_infocloud_listcloud_searchcloud_syncfast_applyfast_searchScored across 7 tools
Each tool has a clearly distinct purpose with descriptions that explicitly differentiate similar tools (e.g., agentic_search vs cloud_search based on query type). There is no functional overlap.
Cloud operations use a consistent 'cloud_' prefix, but 'agentic_search', 'fast_apply', and 'index_status' break the pattern. Mix of verb_noun and adjective_noun styles reduces predictability.
Seven tools is well-scoped for a code search and editing server. Each tool addresses a specific need without redundancy or excessive complexity.
Covers search (local and cloud) and file editing, but lacks tools for reading full file content, deleting files, or managing local files beyond edits. Users may need to rely on external tools for basic operations.
SaaS intelligence for AI agents. 5 unified tools cover 1,000+ services with 91-96% token savings.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Discover, compare, and monitor 1,400+ APIs directly from your AI coding agent.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
