You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add a `javaducker_blame` MCP tool that wraps `git blame` with indexed context — given a file or artifact, return who last touched each section, when, and the commit message. Enriched with JavaDucker metadata (summary, tags, dependencies).
12
+
13
+
## Chapter 1: Git Blame Service
14
+
**Status:** completed
15
+
**Depends on:** none
16
+
17
+
-[x] Create `GitBlameService.java` in `server/service/` (~150 lines) — run `git blame --porcelain <file>` via `ProcessBuilder`, parse output into structured records: `BlameEntry(lineStart, lineEnd, commitHash, author, authorDate, commitMessage, content)`
18
+
-[x] Handle edge cases: file not in git, binary files, files outside PROJECT_ROOT, git not installed
19
+
-[x] Add method `blameForArtifact(artifactId)` — look up `original_client_path` from `artifacts` table, run blame on that path
20
+
-[x] Add method `blameForLines(filePath, startLine, endLine)` — blame a specific range (useful when Claude is looking at a search result with line numbers)
21
+
-[x] Write `GitBlameServiceTest` — test porcelain parsing, file-not-found, range queries
22
+
23
+
**Notes:**
24
+
> Use `--porcelain` format for machine-readable output. Cache blame results in memory (LRU, 50 files) since blame is expensive. PROJECT_ROOT env var gives the repo root.
25
+
26
+
## Chapter 2: REST Endpoint & MCP Tool
27
+
**Status:** completed
28
+
**Depends on:** Chapter 1
29
+
30
+
-[x] Add `GET /api/blame/{artifactId}` endpoint — returns blame entries for the full file, enriched with artifact summary if available
31
+
-[x] Add `POST /api/blame` endpoint — body: `{filePath, startLine?, endLine?}` — blame by path with optional range
32
+
-[x] Add `javaducker_blame` MCP tool to `JavaDuckerMcpServer.java` — params: `file_path` (required), `start_line` (optional), `end_line` (optional). Description: "Show who last changed each line of a file, with commit info. Optionally narrow to a line range."
33
+
-[x] Enrich blame response: for each unique commit, include the commit message. For the file, include artifact summary and dependency count if indexed
34
+
-[x] Write integration test — blame a real file in the repo, verify structure
35
+
36
+
**Notes:**
37
+
> Keep the MCP tool response concise — group consecutive lines by the same commit into ranges, don't return per-line entries for 500-line files. Example: "lines 1-45: alice, 2026-03-20, 'Add auth middleware'"
38
+
39
+
---
40
+
41
+
## Risks
42
+
- git must be available on PATH — fail gracefully with clear error if not
43
+
- Large files produce verbose blame — cap at 500 lines or summarize by commit
Add a `javaducker_explain` MCP tool that returns everything JavaDucker knows about a file in one call: summary, dependency chain, dependents, tags, classification, related plans/ADRs, co-change partners, and blame highlights. A single-call context loader for Claude.
12
+
13
+
## Chapter 1: Explain Service
14
+
**Status:** completed
15
+
**Depends on:** none
16
+
17
+
-[x] Create `ExplainService.java` in `server/service/` (~200 lines) — aggregates data from existing services. Constructor-injected: `ArtifactService`, `DependencyService`, `SearchService`, `ContentIntelligenceService`. Optional: `GitBlameService`, `CoChangeService` (may not exist yet — use try-catch or Optional injection)
18
+
-[x] Add method `explain(artifactId)` — returns a composite map with sections: `file` (name, path, size, status, indexed_at), `summary` (from artifact summary), `dependencies` (imports this file uses), `dependents` (files that import this one), `classification` (doc_type, tags, freshness), `salient_points` (decisions, risks, actions from content intelligence), `related_artifacts` (by concept links), `blame_highlights` (top 3 most recent committers + their commit messages, if GitBlameService available), `co_changes` (top 5 files commonly edited together, if CoChangeService available)
19
+
-[x] Handle missing data gracefully — each section is optional. If a service throws or returns null, that section is omitted, not the whole response
20
+
-[x] Write `ExplainServiceTest` — test with full data, test with partial data (no blame, no co-change), test with unknown artifactId
21
+
22
+
**Notes:**
23
+
> This is a read-only aggregation service. It calls existing services — no new tables, no new data. Its value is combining 6-8 separate API calls into one.
24
+
25
+
## Chapter 2: REST Endpoint & MCP Tool
26
+
**Status:** completed
27
+
**Depends on:** Chapter 1
28
+
29
+
-[x] Add `GET /api/explain/{artifactId}` endpoint — returns the full explain bundle
30
+
-[x] Add `POST /api/explain` endpoint — body: `{filePath}` — resolve to artifact_id first, then explain. If not indexed, return a minimal response with just the file path and a note that it's not indexed
31
+
-[x] Add `javaducker_explain` MCP tool — params: `file_path` (required). Description: "Get everything JavaDucker knows about a file: summary, dependencies, dependents, tags, classification, related plans, blame highlights, and co-change partners. One call for full context."
32
+
-[x] Keep response compact — summaries not full text, top-N for lists (5 deps, 5 dependents, 5 co-changes, 3 blame entries). Include counts so Claude knows there's more if needed
33
+
-[x] Write integration test — explain a real indexed file, verify all sections present
34
+
35
+
**Notes:**
36
+
> This will likely become the most-called MCP tool. Claude should use it before editing any file to understand full context. Keep the response under 2K tokens.
37
+
38
+
---
39
+
40
+
## Risks
41
+
- Response could be large if all sections are populated — enforce limits per section
42
+
- Depends on other quick wins (blame, related) for full richness, but works without them
43
+
44
+
## Open Questions
45
+
- Should explain also return recent search queries that matched this file? (might be noise)
Add a `javaducker_related` MCP tool that finds files commonly edited together by analyzing git log co-change history. When Claude is editing a file, it can ask "what other files usually change with this one?" to avoid missing related updates.
12
+
13
+
## Chapter 1: Co-Change Analysis Service
14
+
**Status:** completed
15
+
**Depends on:** none
16
+
17
+
-[x] Create `CoChangeService.java` in `server/service/` (~180 lines) — run `git log --name-only --pretty=format:"COMMIT:%H" --since="6 months ago"` via `ProcessBuilder`, parse into commit→files map. For a given file, find all commits that touched it, then count co-occurrences of other files across those commits. Rank by frequency
-[x] Add method `getRelatedFiles(filePath, maxResults)` — query cache, return ranked list with co-change count and last shared commit date
21
+
-[x] Filter out noise: ignore files that appear in >50% of all commits (build scripts, lockfiles), ignore commits with >30 files (bulk renames/reformats)
> The git log parse is expensive (~2-5s for large repos) so we cache in DuckDB. Rebuild on demand via endpoint or when staleness is detected. The 6-month window keeps results relevant.
26
+
27
+
## Chapter 2: REST Endpoint & MCP Tool
28
+
**Status:** completed
29
+
**Depends on:** Chapter 1
30
+
31
+
-[x] Add `GET /api/related/{artifactId}` endpoint — look up original_client_path, return co-change partners ranked by frequency
32
+
-[x] Add `POST /api/related` endpoint — body: `{filePath, maxResults?, rebuild?}`. If `rebuild: true`, refresh the co-change cache first
33
+
-[x] Add `javaducker_related` MCP tool — params: `file_path` (required), `max_results` (optional, default 10). Description: "Find files that are commonly edited together with this file, based on git history. Helps identify related files you might need to update."
34
+
-[x] Enrich response: for each related file, include co-change count, last shared commit, and whether it's currently indexed in JavaDucker (with summary if so)
35
+
-[x] Add `POST /api/rebuild-cochange` endpoint — force rebuild the cache
36
+
-[x] Write integration test — build index from real repo, query related files
37
+
38
+
**Notes:**
39
+
> This is one of the most useful tools for Claude — when making a change, knowing what usually changes together prevents incomplete PRs.
40
+
41
+
---
42
+
43
+
## Risks
44
+
- Git log parsing on very large repos (10K+ commits) could be slow — the 6-month window mitigates this
45
+
- Projects without git history return empty results — handle gracefully
46
+
47
+
## Open Questions
48
+
- Should the co-change cache auto-rebuild on a timer, or only on demand?
0 commit comments