mirror of
https://github.com/abhigyanpatwari/GitNexus.git
synced 2026-10-07 02:58:02 +00:00
9ff7337f1e
* fix(mcp): advertise search_query/statement params for query/cypher tools (#2175) Claude Code drops a tool-call argument named exactly 'query', making the query and cypher tools unusable from it. Rename the advertised required parameters to search_query and statement so the client transmits them. Handler-side backward-compat for the legacy 'query' key follows in the next commit. * fix(mcp): accept search_query/statement with legacy query fallback (#2175) Resolve the new advertised param names in the backend while still accepting the legacy 'query' key, so curl/HTTP, other MCP clients, the CLI, the group path, and the internal executeCypher() all keep working. Alias is normalized once at the callTool chokepoint (covers group-forward + search alias); query() and cypher() dual-read defensively. New name wins when both are supplied. Updates the required-error message and adds dual-accept unit + integration coverage. * fix(cli): pass canonical search_query/statement params to query/cypher tools (#2175) Stop the CLI from depending on the deprecated 'query' alias. No user-facing change — the positional args are unchanged and the backend accepts both keys. * fix(mcp): generators advertise search_query in query() examples (#2175) Update the three doc/example generators (ai-context AGENTS/CLAUDE block, skill-gen community skills, resources repo hint) so future analyze runs emit query({search_query: ...}) — the param name Claude Code actually transmits. Tests assert the new form is present and the legacy query({query: form is absent (the #2059 generator-test pattern). * docs(mcp): advertise search_query/statement in skill & guidance examples (#2175) Sync the committed agent-facing docs to the renamed params so a Claude Code agent following them emits the transmittable key: AGENTS.md/CLAUDE.md gitnexus block, the canonical gitnexus/skills/* source and its installed/plugin/cursor mirrors, and the README examples. Scoped rewrite of the two call prefixes only (query({query: -> search_query, cypher({query: -> statement). * style(mcp): prettier line-wrap for #2175 alias-resolution edits * fix(review): uniform search_query precedence + cypher empty guard (#2175) Code-review findings (correctness/adversarial/api-contract/maintainability consensus): - Group-mode query inverted the 'new name wins' rule: the callTool chokepoint backfilled params.query only when empty and the @group-forward read params.query directly, so a both-keys (or whitespace-legacy) group call let the legacy value win — unlike the local path. Replace the hidden param mutation with a self-contained 'search_query ?? query' resolve at the group-forward; precedence is now uniformly new-wins at every consumer site. - cypher() now returns the same friendly required-param error as query() when neither statement nor query is supplied, instead of a raw DB prepare error. - Document the legacy alias as permanent (third-party clients may send query=). Adds group-forward alias tests (both-keys + legacy-only), empty/whitespace search_query, the search-alias path, and the cypher empty-statement guard. * fix(review): non-string alias safety + drop stale chokepoint comment (#2175) Tri-review findings (correctness/adversarial/security + maintainability): - Non-string statement/search_query/query (the MCP envelope is not schema-validated) hit .trim() and threw TypeError to the server boundary instead of a friendly required-param error. Introduce resolveAliasString() (new name wins; non-string -> undefined) used by query(), cypher(), and the group-forward, so all three return the structured error. Empirically verified (123 ?? '' -> 123, (123).trim() throws) — this overrides a critic refutation that mis-read ?? as a string coercion. - Remove the stale query() comment claiming alias resolution happens at a callTool chokepoint; that mutation was removed earlier in this PR — each site resolves the alias itself. - Document GroupToolPort.query's intentionally-narrower required type vs the wider LocalBackend impl. Adds non-string and empty-new-key precedence tests. * fix(mcp): alias falls back to legacy value when new key is blank (#2175) PR #2186 review finding: resolveAliasString used `canonical ?? legacy` (nullish), so an explicitly empty/whitespace new-name value (e.g. {search_query:'', query:'real'}) won and was rejected — discarding a valid legacy value, contradicting the 'new name wins when both supplied' intent. Resolve to the first NON-BLANK string instead (new preferred when it carries a real value, else legacy). Covers query(), cypher(), and the group-forward (all route through the helper); non-string still resolves to a friendly error. Flips the presence-based test and adds whitespace/cypher/group fallback cases. * fix(mcp): drop legacy "query" mention from query/cypher schema descriptions (#2175) PR #2186 review finding: the search_query/statement inputSchema descriptions named the legacy "query" key — the exact arg Claude Code drops — and description text is read by an LLM choosing arguments, weakly nudging it to send "query". Trim the descriptions to their clean form and move the legacy-alias note to a code comment next to the schema (preserved for maintainers / non-CC clients). properties/required unchanged (no `query`).
78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
---
|
|
name: gitnexus-exploring
|
|
description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
|
|
---
|
|
|
|
# Exploring Codebases with GitNexus
|
|
|
|
## When to Use
|
|
|
|
- "How does authentication work?"
|
|
- "What's the project structure?"
|
|
- "Show me the main components"
|
|
- "Where is the database logic?"
|
|
- Understanding code you haven't seen before
|
|
|
|
## Workflow
|
|
|
|
```
|
|
1. READ gitnexus://repos → Discover indexed repos
|
|
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
|
|
3. query({search_query: "<what you want to understand>"}) → Find related execution flows
|
|
4. context({name: "<symbol>"}) → Deep dive on specific symbol
|
|
5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow
|
|
```
|
|
|
|
> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
|
|
|
|
## Checklist
|
|
|
|
```
|
|
- [ ] READ gitnexus://repo/{name}/context
|
|
- [ ] query for the concept you want to understand
|
|
- [ ] Review returned processes (execution flows)
|
|
- [ ] context on key symbols for callers/callees
|
|
- [ ] READ process resource for full execution traces
|
|
- [ ] Read source files for implementation details
|
|
```
|
|
|
|
## Resources
|
|
|
|
| Resource | What you get |
|
|
| --------------------------------------- | ------------------------------------------------------- |
|
|
| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
|
|
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
|
|
| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
|
|
| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
|
|
|
|
## Tools
|
|
|
|
**query** — find execution flows related to a concept:
|
|
|
|
```
|
|
query({search_query: "payment processing"})
|
|
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
|
|
→ Symbols grouped by flow with file locations
|
|
```
|
|
|
|
**context** — 360-degree view of a symbol:
|
|
|
|
```
|
|
context({name: "validateUser"})
|
|
→ Incoming calls: loginHandler, apiMiddleware
|
|
→ Outgoing calls: checkToken, getUserById
|
|
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
|
|
```
|
|
|
|
## Example: "How does payment processing work?"
|
|
|
|
```
|
|
1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
|
|
2. query({search_query: "payment processing"})
|
|
→ CheckoutFlow: processPayment → validateCard → chargeStripe
|
|
→ RefundFlow: initiateRefund → calculateRefund → processRefund
|
|
3. context({name: "processPayment"})
|
|
→ Incoming: checkoutHandler, webhookHandler
|
|
→ Outgoing: validateCard, chargeStripe, saveTransaction
|
|
4. Read src/payments/processor.ts for implementation details
|
|
```
|