Skip to main content
Glama
deenesjakoruzh
salman-arefin74

Repo Therapist

by salman-arefin74
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Repo Therapist 🛋️

압박 속에서도 코드베이스가 스스로를 설명합니다

이 MCP 서버는 전적으로 Cursor를 사용하여 구축되었습니다

Repo Therapist는 모든 저장소를 쿼리 가능하고 설명 가능한 지식으로 바꾸는 MCP(Model Context Protocol) 서버입니다. Cursor를 통해 코드베이스에 대해 질문하고 구조화된 통찰력 있는 답변을 얻으세요.

기능

Cursor에게 다음과 같이 질문할 수 있습니다:

  • "이 서비스는 왜 이렇게 구조화되어 있나요?"

  • "이것을 제거하면 무엇이 깨질까요?"

  • "이 저장소의 어떤 부분이 걱정되나요?"

Repo Therapist는 내부적으로 다음을 수행합니다:

  • 저장소 구조 및 파일 읽기

  • git 기록 및 커밋 패턴 분석

  • 코드와 변경 빈도 상관관계 분석

  • 복잡성 핫스팟 및 위험 식별

Related MCP server: Code Understanding MCP Server

사용 가능한 도구

도구

설명

analyze_repo(path)

저장소 분석 - 가장 먼저 실행하세요

get_snapshot(section?)

저장소의 정적 스냅샷(기초 데이터) 가져오기

get_history(section?)

git 기록 분석 가져오기 (시간 차원)

why_is_this_weird(file_path)

특정 파일이 왜 그렇게 되어 있는지 설명

ask_repo(question)

분석된 저장소에 대해 질문하기

repo_summary()

상위 수준의 개요 가져오기

risk_report()

위험 평가 보고서 생성

기초 데이터: 스냅샷

analyze_repo를 실행하면 Repo Therapist는 저장소에 대한 권위 있는 진실의 원천인 정적 스냅샷을 생성합니다. 이 스냅샷에는 다음이 포함됩니다:

{
  "files": [...],           // Every file with path, language, line count
  "languages": {...},       // Language breakdown with percentages
  "entryPoints": [...],     // Detected entry points with confidence levels
  "configs": {...},         // Parsed package.json, tsconfig, Dockerfile, CI configs
  "directories": [...]      // Directory structure with inferred purposes
}

중요성: LLM은 추측하지 말고 이 스냅샷 데이터를 인용해야 합니다. "이 저장소는 어떤 언어를 사용하나요?"라고 물으면 LLM이 가정하는 것이 아니라 스냅샷에서 답변이 나옵니다.

get_snapshot을 사용하여 특정 섹션을 검색하세요:

  • get_snapshot(section: "files") - 메타데이터가 포함된 모든 파일

  • get_snapshot(section: "languages") - 언어 통계

  • get_snapshot(section: "entryPoints") - 감지된 진입점

  • get_snapshot(section: "configs") - 파싱된 설정 파일

  • get_snapshot(section: "directories") - 디렉토리 구조

  • get_snapshot() - 전체 요약

Git Historian: 시간 차원

Git Historian은 커밋 기록을 분석하여 코드가 왜 그렇게 되어 있는지 설명합니다. 여기서부터는 단순한 분석을 넘어섭니다.

{
  "fileChurn": { "auth.ts": { "totalCommits": 47, "churnScore": 85 } },
  "authors": { "auth.ts": ["alice", "bob", "charlie"] },
  "fragileFiles": [{ "path": "auth.ts", "reasons": ["high-churn", "many-authors"] }],
  "hotPaths": [...],
  "stableCore": [...]
}

이를 통해 다음 질문에 답할 수 있습니다:

  • "이게 왜 이상한가요?" → "6개월 동안 12번이나 다시 작성되었기 때문입니다."

  • "이 파일의 소유자는 누구인가요?" → "불분명합니다 - 4명이 수정했지만, 30% 이상 기여한 사람은 없습니다."

  • "무엇을 조심해야 하나요?" → "이 5개의 파일은 취약하고 버그가 발생하기 쉽습니다."

get_history를 사용하여 특정 측면을 검색하세요:

  • get_history(section: "churn") - 파일 변경 빈도 및 변동성

  • get_history(section: "authors") - 기여자 통계

  • get_history(section: "fragile") - 문제를 일으킬 가능성이 있는 파일

  • get_history(section: "hotPaths") - 핫 경로 vs 안정적인 코어

  • get_history(section: "timeline") - 주요 이벤트 및 커밋 패턴

  • get_history(section: "ownership") - 소유권 정보

  • get_history() - 전체 요약

특정 파일 분석에는 why_is_this_weird를 사용하세요:

Use why_is_this_weird on "src/auth/login.ts"

인용문과 함께 자세한 설명을 반환합니다:

# Why is "src/auth/login.ts" the way it is?

## Change History
- Total commits: 47
- Authors: 5 (alice, bob, charlie, dave, eve)
- Churn score: 85 ⚠️ HIGH

## 🔍 Why It's Unusual
**Heavily modified:** This file has been changed 47 times...
**Many hands:** 5 different people have modified this file...

설정

1. 의존성 설치

cd repo-therapist
npm install

2. 프로젝트 빌드

npm run build

3. Cursor에 추가

Cursor 설정 → MCP → 새 MCP 서버 추가:

{
  "mcpServers": {
    "repo-therapist": {
      "command": "node",
      "args": ["/FULL/PATH/TO/repo-therapist/dist/index.js"]
    }
  }
}

중요: /FULL/PATH/TO/를 repo-therapist 폴더의 실제 절대 경로로 바꾸세요.

예시:

{
  "mcpServers": {
    "repo-therapist": {
      "command": "node",
      "args": ["/Users/saar/Projects/private/repo-therapist/dist/index.js"]
    }
  }
}

4. Cursor 재시작

MCP 설정을 추가한 후, 변경 사항을 적용하려면 Cursor를 재시작하세요.

FAQ

repo-therapist를 별도로 실행해야 하나요?

아니요. Cursor가 자동으로 MCP 서버를 시작하고 관리합니다. Cursor의 MCP 설정에 구성을 추가하면 Cursor는 다음을 수행합니다:

  • 필요할 때 node dist/index.js 프로세스 시작

  • 백그라운드에서 계속 실행 유지

  • stdio(표준 입출력)를 통해 통신

한 번 빌드(npm run build)하고, 설정을 추가하고, Cursor를 재시작하기만 하면 됩니다. 끝입니다.

질문은 어디서 하나요?

일반 Cursor 채팅 (Cmd+L 또는 채팅 패널)에서 합니다. 차이점은 질문하는 방식입니다:

  • MCP 없이: "이 저장소는 무엇을 하나요?" → Cursor가 내장 도구 사용

  • Repo Therapist와 함께: "/path/to/repo에서 analyze_repo를 사용해" → Cursor가 MCP 도구 호출

Cursor에게 repo-therapist 도구를 사용하도록 명시적으로 지시합니다. Cursor는 이를 사용할 수 있는 추가 기능으로 인식합니다.

일반 Cursor 채팅과의 차이점은 무엇인가요?

일반 Cursor 채팅

Repo Therapist와 함께

필요할 때 파일 읽기

전체 저장소 구조 사전 분석

git 기록 인식 없음

커밋 패턴 및 변경 빈도 분석

읽은 내용을 바탕으로 답변

구조화된 분석을 바탕으로 답변

위험 감지 없음

복잡성 핫스팟 식별

일반적인 코드 이해

도메인별 통찰력 ("무엇이 걱정되나요?")

핵심 차이점: Repo Therapist는 사전에 구조화된 분석을 수행하고 저장하므로, "어떤 파일이 가장 자주 변경되나요?" 또는 "위험 요소는 무엇인가요?"와 같은 질문에 Cursor가 매번 파악할 필요 없이 미리 계산된 데이터로 답변할 수 있습니다.

Cursor는 똑똑하지만 반응형입니다. Repo Therapist는 Cursor가 참조할 수 있는 코드베이스에 대한 "브리핑 문서"를 제공한다고 생각하세요.

사용법

설정 후 Cursor 채팅에서 Repo Therapist를 사용할 수 있습니다:

1단계: 저장소 분석

먼저 탐색하려는 저장소를 분석하세요:

Use analyze_repo to analyze /path/to/some/repo

2단계: 질문하기

이제 질문할 수 있습니다:

Use ask_repo to answer: "What does this repo do?"
Use ask_repo to answer: "Which parts of this repo scare you?"
Use ask_repo to answer: "What will break if I remove the auth module?"

3단계: 보고서 받기

요약 받기:

Use repo_summary to show me an overview

위험 평가 받기:

Use risk_report to identify potential issues

질문 예시

  • "이 저장소는 무엇을 하나요?"

  • "코드는 어떻게 구조화되어 있나요?"

  • "어떤 기술 스택이 사용되고 있나요?"

  • "의존성을 보여줘"

  • "가장 큰 파일은 무엇인가요?"

  • "어떤 파일이 가장 자주 변경되나요?"

  • "기여자는 누구인가요?"

  • "최근 커밋은 무엇인가요?"

  • "어떤 부분이 걱정되나요?"

  • "X를 변경하면 무엇이 깨질까요?"

개발

개발 모드에서 실행

npm run dev

프로덕션용 빌드

npm run build

테스트 실행

npm test              # Run all tests
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report

테스트 가이드라인

참고: 새로운 기능을 구현할 때는 항상 단위 테스트를 추가하세요.

테스트는 tests/에 위치하며 Vitest를 사용합니다. 테스트 구조는 소스 구조를 반영합니다:

tests/
├── fixtures/           # Test utilities and mock repos
│   └── setup.ts        # Helper functions for creating test repos
├── scanner/            # Scanner module tests
├── historian/          # Historian module tests
├── tools/              # Tool tests
└── cache.test.ts       # Cache tests

새 기능을 추가할 때:

  1. 적절한 tests/ 하위 디렉토리에 테스트 생성

  2. git 관련 테스트에는 fixtures/setup.ts의 createTestRepo() 사용

  3. afterAll에서 cleanupTestRepo()로 테스트 저장소 정리

  4. 커밋하기 전에 npm test를 실행하여 모든 테스트 통과 확인

프로젝트 구조

repo-therapist/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── cache.ts              # In-memory repo cache
│   ├── types.ts              # TypeScript interfaces
│   ├── scanner/              # Static snapshot engine (Step 2)
│   │   ├── index.ts          # Scanner exports
│   │   ├── types.ts          # Snapshot type definitions
│   │   └── scan-repo.ts      # Repository scanner
│   ├── historian/            # Git history analyzer (Step 3)
│   │   ├── index.ts          # Historian exports
│   │   ├── types.ts          # History type definitions
│   │   └── analyze-history.ts # Git history analysis
│   └── tools/
│       ├── analyze-repo.ts   # Repository analyzer (orchestrates all)
│       ├── get-snapshot.ts   # Snapshot retrieval (ground truth)
│       ├── get-history.ts    # History retrieval (time dimension)
│       ├── ask-repo.ts       # Question answering
│       ├── repo-summary.ts   # Summary generator
│       └── risk-report.ts    # Risk assessment
├── tests/                    # Unit tests
│   ├── fixtures/             # Test utilities
│   ├── scanner/              # Scanner tests
│   ├── historian/            # Historian tests
│   └── tools/                # Tool tests
├── package.json
├── tsconfig.json
├── vitest.config.ts          # Test configuration
└── README.md

기술 스택

  • TypeScript - 타입 안전 코드베이스

  • @modelcontextprotocol/sdk - MCP 서버 구현

  • simple-git - Git 기록 분석

  • ts-morph - TypeScript/JavaScript AST 파싱 (계획 중)

  • glob - 파일 패턴 매칭

로드맵

  • [ ] ts-morph를 사용한 AST 기반 코드 분석

  • [ ] 분석 결과를 JSON/SQLite에 영구 저장

  • [ ] 의존성 그래프 시각화

  • [ ] 보안 취약점 탐지

  • [ ] 테스트 커버리지 분석

  • [ ] 사용자 정의 질문 핸들러

라이선스

MIT

Available Tools

7 tools
analyze_repoA

Analyze a repository to understand its structure, dependencies, and git history. Run this first before asking questions.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path to the repository to analyze

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It describes what the tool does (analyze structure, dependencies, git history) but does not disclose side effects, permissions, or output format. Adequate but lacks depth on behavioral traits like mutability or performance impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose, second provides usage guidance. Extremely concise, front-loaded with essential information, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description lacks details on what the analysis returns (e.g., report structure, how to use results). It hints at follow-up use ('before asking questions') but does not fully equip an agent to handle output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, 'path', is described in the schema as 'Absolute path to the repository to analyze'. The description does not add extra meaning beyond what the schema already provides. With 100% schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes a repository for structure, dependencies, and git history, and provides a usage directive ('Run this first before asking questions'), which distinctively positions it among siblings like ask_repo and get_history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: run this before asking questions. It implies when to use but does not explicitly list alternatives or when not to use, though the sibling context partially compensates.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ask_repoC

Ask a question about an analyzed repository. Questions can be about structure, purpose, dependencies, patterns, or concerns.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional: path to repo if different from last analyzed
questionYesThe question to ask about the repository (e.g., 'What does this repo do?', 'Why is the auth service structured this way?')

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of behavioral disclosure. It does not state that the tool is read-only, whether it requires prior analysis, or any side effects. The description lacks behavioral details beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and to the point. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should explain what the agent can expect as a response (e.g., an answer text). It also does not mention that the repository must be analyzed first, though sibling tools imply context. The description is incomplete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already contains examples for the 'question' parameter. The description adds marginal value by listing question types, but those are similar to schema examples. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'ask' and the resource 'repository', and provides examples of question categories (structure, purpose, etc.). However, it does not explicitly distinguish from sibling tools like 'repo_summary' or 'why_is_this_weird', which may also answer questions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites (e.g., that the repository must have been analyzed first). It only states what the tool does.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_historyB

Get git history analysis - the time dimension. Reveals WHY code is the way it is: file churn, ownership, fragile files, hot paths vs stable core.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional: path to repo if different from last analyzed
sectionNoWhich aspect of history to retrieve: 'churn' (file change frequency), 'authors' (contributor stats), 'fragile' (problem files), 'hotPaths' (volatile vs stable), 'timeline' (events), 'ownership' (who owns what), 'all' (summary).

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description carries full burden. It mentions what the tool reveals (churn, authorship, etc.) but omits behavioral details: whether it modifies state, requires authentication, or handles large repos. As a likely read-only analysis, this gap limits agent understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, front-loaded sentence with purpose and examples. Efficient but could briefly list alternative uses or output format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks usage guidelines, output schema, and behavioral details. With six sibling tools, agent needs more context to choose correctly. Missing information on return format or prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with clear descriptions for both parameters (path, section with enums). Description adds no further semantic value beyond what the schema provides; baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool's verb ('Get'), resource ('git history analysis'), and specific insights ('file churn, ownership, fragile files, hot paths vs stable core'). It emphasizes the 'time dimension', distinguishing it from sibling tools like get_snapshot or repo_summary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives (e.g., analyze_repo, risk_report). The description hints at 'time dimension' but lacks exclusions or context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_snapshotA

Get the static snapshot (ground truth) of the repository. This is the authoritative source - LLMs must cite this data, not guess. Use section parameter to get specific data.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional: path to repo if different from last analyzed
sectionNoWhich section of the snapshot to retrieve. 'all' returns a summary view.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes a read operation but does not disclose error handling, caching behavior, or response scope beyond inferring from section parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose and authoritative emphasis. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description conveys the tool's role as a source of truth. Could elaborate on return format, but sufficient for a simple retrieval tool with well-defined params.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters, baseline 3. The description adds 'Use section parameter' but does not provide additional meaning beyond the schema's enum or path description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a static snapshot as the authoritative ground truth, distinguishing it from sibling tools that involve analysis or generation. It emphasizes this data should be cited, not guessed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear guidance on when to use (for ground truth) and suggests using the section parameter. However, no explicit when-not-to-use or alternatives, though siblings like analyze_repo imply different use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

repo_summaryB

Get a high-level summary of the analyzed repository including tech stack, structure, and key components.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional: path to repo if different from last analyzed

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavioral traits, but it only states the action. It does not mention that the tool requires a repository to have been analyzed, that it is read-only, or any constraints like 'last analyzed' implication.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one optional parameter and no output schema, the description is minimally complete. However, it omits details about the output format and prerequisites (e.g., requiring prior analysis), which would be helpful for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the description does not add meaning beyond what is already in the schema for the 'path' parameter. The baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets a high-level summary including tech stack, structure, and key components, which is specific and informative. However, it does not explicitly differentiate from sibling tools like ask_repo or analyze_repo, but the distinct purpose is inferable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor any context about prerequisites (e.g., requiring a prior analysis). The description is purely declarative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

risk_reportC

Generate a risk assessment report identifying code smells, complexity hotspots, and areas that might cause problems.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional: path to repo if different from last analyzed

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose whether the tool is read-only, requires permissions, or has side effects. It only states it generates a report, leaving behavioral traits unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that directly states the tool's purpose without extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a risk assessment report, the description lacks details on the report's structure, output format, or behavior. It does not compensate for the absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single optional parameter 'path' is already fully described in the input schema. The tool description adds no additional meaning beyond the schema, achieving baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a risk assessment report focusing on code smells and complexity hotspots. However, it does not differentiate from sibling tools like analyze_repo or repo_summary, which may have overlapping purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool vs alternatives such as analyze_repo, repo_summary, or why_is_this_weird. The description lacks context on appropriate use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

why_is_this_weirdA

Explain why a specific file is the way it is, based on git history. Answers questions like 'Why is this file so complex?' with data: 'Because it's been rewritten 12 times by 5 different people.'

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional: path to repo if different from last analyzed
file_pathYesThe relative path to the file to analyze (e.g., 'src/auth/login.ts')

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates the tool uses git history to answer questions, but with no annotations, it does not disclose whether the tool modifies data, requires special permissions, or the exact nature of its operations. It is adequate but lacks full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of two sentences and an example. It is front-loaded with the primary purpose and efficiently conveys value without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and a moderate number of parameters, the description explains the tool's behavior well, including an example output. However, it does not address edge cases like files with no history or error conditions, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for both parameters, so the schema itself provides parameter meaning. The description adds context about the analysis type (git history, complexity) but does not extend parameter semantics significantly beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Explain why a specific file is the way it is, based on git history.' It provides a concrete example question and answer, distinguishing it from sibling tools like get_history or analyze_repo.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for understanding file complexity via git history, but it does not explicitly state when to use this tool versus alternatives (e.g., get_history for raw history), nor does it provide any 'when not to use' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.0.0
    • First observedanalyze_repo
    • First observedask_repo
    • First observedget_history
    • First observedget_snapshot
    • First observedrepo_summary
    • First observedrisk_report
    • First observedwhy_is_this_weird
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.5/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: analyze_repo is for initial analysis, ask_repo for questions, get_history for git history, get_snapshot for authoritative data, repo_summary for high-level summary, risk_report for risk assessment, and why_is_this_weird for explaining file history. No overlap.

Naming Consistency3/5

Most tools follow a verb_noun pattern (analyze_repo, ask_repo, get_history, get_snapshot), but repo_summary and risk_report are noun_noun, and why_is_this_weird is a full sentence, creating inconsistency.

Tool Count5/5

Seven tools is well-scoped for a repository analysis server, providing essential functionality without being overwhelming or insufficient.

Completeness4/5

The tool set covers key aspects: analysis, Q&A, history, snapshot, summary, and risk assessment. Minor gaps like direct file search or comparison are missing but can be partially addressed by ask_repo.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers