feat: rework tool and server to be agent-oriented

[greynewell]

Summary by CodeRabbit

• Documentation

  • Updated documentation to clarify tool's codebase analysis capabilities and intended use cases.
  • Added quick-start guide with step-by-step workflow examples.
  • Enhanced parameter descriptions and caching guidance.

• Chores

  • Updated tool identifier name and expanded descriptions to better reflect current functionality.
  • Improved parameter documentation for cache key formatting and filtering options.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The tool has been rebranded and repositioned from a Supermodel API-specific graph generator to a general-purpose codebase analyzer. The changes include renaming the tool from create_supermodel_graph_graphs to analyze_codebase, updating documentation across README and server instructions, and enhancing parameter descriptions with guidance on caching and response optimization.

Changes

Cohort / File(s)	Summary
Documentation & Instructions README.md, src/server.ts	Updated tool purpose, usage examples, and workflow guidance. README now emphasizes codebase analysis, architecture understanding, and includes quick-start sequences. Server instructions replaced with codebase analysis-focused narrative.
Tool Definition & Schema src/tools/create-supermodel-graph.ts	Tool name changed from create_supermodel_graph_graphs to analyze_codebase. Enhanced descriptions for Idempotency-Key (cache key format guidance) and jq_filter (emphasized for response size reduction). Expanded tool description.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A tool once bound by Supermodel's name,
Now breaks free from its narrow frame,
To analyze_codebase it transforms with grace,
Helping AI agents understand code's vast space. 🚀📊

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: rework tool and server to be agent-oriented' directly reflects the main change: refactoring the tool from 'create_supermodel_graph_graphs' to 'analyze_codebase' with agent-focused documentation and UX improvements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

src/server.ts (1)

21-21: Consider extracting this massive string into a separate file.

This 5000+ character instruction string is getting pretty unwieldy. When someone needs to update the docs, they'll have to scroll through a ton of escaped text and newlines.

Here's the thing: If you move this to something like instructions.txt or instructions.md in a /docs folder, you can:

• Edit it with proper formatting/syntax highlighting
• Version control it more cleanly (diffs will be readable)
• Potentially reuse it in the README or other places

Quick example of how you'd do it:

import { readFileSync } from 'fs';
import { join } from 'path';

// In constructor:
instructions: readFileSync(join(__dirname, '../docs/instructions.txt'), 'utf-8')

The content itself is solid and helpful, just the location/format could be improved.

src/tools/create-supermodel-graph.ts (1)

26-26: Super helpful description, but same maintainability concern as server.ts.

The content here is really solid - it tells the user exactly when to use the tool, what they'll get, and how to use it. The jq filter examples are great.

But like the instructions in server.ts, this 1000+ character string is going to be a pain to maintain. Every time someone wants to update the docs, they're editing a giant string with \n everywhere.

Consider: Could you share a constants file between this and server.ts for common text blocks? Or generate the description from a template? Something like:

import { TOOL_DESCRIPTION } from './constants';

export const tool: Tool = {
  name: 'analyze_codebase',
  description: TOOL_DESCRIPTION,
  // ...
}

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8c68e88 and 1998a43.

📒 Files selected for processing (3)

• README.md
• src/server.ts
• src/tools/create-supermodel-graph.ts

🧰 Additional context used

🪛 LanguageTool

README.md

[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...flows/ci.yml) MCP server that provides deep codebase analysis to AI agents via the ...

(DEEP_PROFOUND)

🔇 Additional comments (5)

README.md (2)

7-7: LGTM! Clear description of the tool's purpose.

The updated description accurately reflects the tool's capabilities. The static analysis hint about "deep" being weak wording is a false positive here - "deep codebase analysis" is perfectly appropriate technical terminology for graph-based static analysis that goes beyond surface-level scanning.

---

129-173: Great job on the comprehensive documentation!

This section does a really nice job of explaining:

• When to use the tool (concrete scenarios)
• What you get back (different graph types)
• How to get started (step-by-step)

The parameters table is super clear, and showing the actual git commands (git archive, git rev-parse) makes it easy for users to get started without hunting through docs.

One tiny thing: You might want to add a note about what happens if the ZIP file path doesn't exist or isn't readable. Right now the error handling is in the code, but users might appreciate a heads-up in the docs like "Make sure the file path is absolute and readable by the MCP server process."

src/tools/create-supermodel-graph.ts (3)

24-24: Perfect alignment with the PR objectives.

The tool rename from create_supermodel_graph_graphs to analyze_codebase is much clearer and more agent-friendly. "Analyze codebase" immediately tells you what it does, whereas the old name was pretty cryptic.

---

36-36: Nice addition of the concrete git command!

Before: Users had to figure out how to generate the hash themselves.
Now: Just copy-paste git rev-parse --short HEAD.

This is the kind of small detail that makes a tool much easier to use.

---

42-42: Good emphasis on using the filter.

Changing from "A jq filter to apply..." to "STRONGLY RECOMMENDED to reduce response size" makes it clear this isn't just a nice-to-have. Without filtering, the response could be huge and eat up the agent's context window.

[jonathanpopham]

I think your pr is good. analyze_codebase is far more intuitive than the previous name. The only improvement that sticks out to me is that an example output may help the machine.