@supermodeltools/mcp-server 0.4.0 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +92 -12
- package/dist/server.js +1 -1
- package/dist/tools/create-supermodel-graph.js +4 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@supermodeltools/mcp-server)
|
|
4
4
|
[](https://modelcontextprotocol.io)
|
|
5
|
+
[](https://github.com/supermodeltools/mcp/actions/workflows/ci.yml)
|
|
5
6
|
|
|
6
|
-
MCP server that
|
|
7
|
+
MCP server that provides deep codebase analysis to AI agents via the [Supermodel API](https://docs.supermodeltools.com). Enables Claude to understand code structure, dependencies, and relationships by generating comprehensive graphs from any repository. Use this to help AI agents explore unfamiliar code, plan refactorings, assess change impact, and understand system architecture.
|
|
7
8
|
|
|
8
9
|
## Install
|
|
9
10
|
|
|
@@ -19,13 +20,52 @@ npx @supermodeltools/mcp-server
|
|
|
19
20
|
|
|
20
21
|
## Configuration
|
|
21
22
|
|
|
22
|
-
Get your API key from the [Supermodel Dashboard](https://supermodeltools.com
|
|
23
|
+
Get your API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com).
|
|
23
24
|
|
|
24
25
|
| Variable | Description |
|
|
25
26
|
|----------|-------------|
|
|
26
27
|
| `SUPERMODEL_API_KEY` | Your Supermodel API key (required) |
|
|
27
28
|
| `SUPERMODEL_BASE_URL` | Override API base URL (optional) |
|
|
28
29
|
|
|
30
|
+
### Global Setup (Recommended)
|
|
31
|
+
|
|
32
|
+
Instead of adding your API key to each MCP config file, you can set it globally in your shell profile. This keeps your key in one place and automatically makes it available to all MCP clients.
|
|
33
|
+
|
|
34
|
+
**For Zsh (macOS default):**
|
|
35
|
+
|
|
36
|
+
Add to `~/.zshrc`:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
export SUPERMODEL_API_KEY="your-api-key"
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**For Bash:**
|
|
43
|
+
|
|
44
|
+
Add to `~/.bashrc` or `~/.bash_profile`:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
export SUPERMODEL_API_KEY="your-api-key"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Then reload your shell:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
source ~/.zshrc # or ~/.bashrc
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
With the API key set globally, you can omit the `env` block from your MCP configs:
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"supermodel": {
|
|
62
|
+
"command": "npx",
|
|
63
|
+
"args": ["-y", "@supermodeltools/mcp-server"]
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
29
69
|
## Usage
|
|
30
70
|
|
|
31
71
|
### Cursor
|
|
@@ -66,30 +106,70 @@ Add to `claude_desktop_config.json`:
|
|
|
66
106
|
|
|
67
107
|
### Claude Code
|
|
68
108
|
|
|
109
|
+
Add the MCP server with your API key:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
claude mcp add supermodel --env SUPERMODEL_API_KEY=your-api-key -- npx -y @supermodeltools/mcp-server
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Or if `SUPERMODEL_API_KEY` is already set in your shell environment:
|
|
116
|
+
|
|
69
117
|
```bash
|
|
70
118
|
claude mcp add supermodel -- npx -y @supermodeltools/mcp-server
|
|
71
119
|
```
|
|
72
120
|
|
|
121
|
+
Verify installation:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
claude mcp list
|
|
125
|
+
```
|
|
126
|
+
|
|
73
127
|
## Tools
|
|
74
128
|
|
|
75
|
-
### `
|
|
129
|
+
### `analyze_codebase`
|
|
76
130
|
|
|
77
|
-
|
|
131
|
+
Analyzes code structure, dependencies, and relationships across a repository. Use this to understand unfamiliar codebases, plan refactorings, assess change impact, or map system architecture.
|
|
78
132
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
133
|
+
**When to use:**
|
|
134
|
+
- Exploring new codebases
|
|
135
|
+
- Planning refactors or architectural changes
|
|
136
|
+
- Understanding dependencies between modules
|
|
137
|
+
- Mapping call relationships and code flow
|
|
138
|
+
- Assessing the impact of proposed changes
|
|
84
139
|
|
|
85
|
-
**
|
|
140
|
+
**What you get:**
|
|
141
|
+
- Dependency graphs (module/package relationships)
|
|
142
|
+
- Call graphs (function-level call hierarchies)
|
|
143
|
+
- Domain classifications (architectural patterns)
|
|
144
|
+
- AST relationships (structural analysis)
|
|
145
|
+
- Summary statistics (languages, complexity, file counts)
|
|
146
|
+
|
|
147
|
+
**Parameters:**
|
|
148
|
+
|
|
149
|
+
| Argument | Type | Required | Description |
|
|
150
|
+
|----------|------|----------|-------------|
|
|
151
|
+
| `file` | string | Yes | Path to repository ZIP file |
|
|
152
|
+
| `Idempotency-Key` | string | Yes | Cache key in format `{repo}:{type}:{hash}` |
|
|
153
|
+
| `jq_filter` | string | No | jq filter to extract specific data (strongly recommended) |
|
|
154
|
+
|
|
155
|
+
**Quick start:**
|
|
86
156
|
|
|
87
157
|
```bash
|
|
158
|
+
# 1. Create ZIP from your git repo
|
|
88
159
|
git archive -o /tmp/repo.zip HEAD
|
|
160
|
+
|
|
161
|
+
# 2. Get commit hash for cache key
|
|
162
|
+
git rev-parse --short HEAD
|
|
163
|
+
# Output: abc123
|
|
164
|
+
|
|
165
|
+
# 3. Ask Claude to analyze
|
|
166
|
+
# "Analyze the codebase at /tmp/repo.zip using key myproject:supermodel:abc123"
|
|
89
167
|
```
|
|
90
168
|
|
|
91
|
-
**Example
|
|
92
|
-
|
|
169
|
+
**Example prompts:**
|
|
170
|
+
- "Analyze the codebase at /tmp/repo.zip to understand its architecture"
|
|
171
|
+
- "Before I refactor the authentication module, analyze /tmp/repo.zip to show me what depends on it"
|
|
172
|
+
- "What's the structure of the codebase in /tmp/repo.zip?"
|
|
93
173
|
|
|
94
174
|
## Troubleshooting
|
|
95
175
|
|
package/dist/server.js
CHANGED
|
@@ -18,7 +18,7 @@ class Server {
|
|
|
18
18
|
version: '0.0.1',
|
|
19
19
|
}, {
|
|
20
20
|
capabilities: { tools: {}, logging: {} },
|
|
21
|
-
instructions: 'This MCP server provides tools for
|
|
21
|
+
instructions: 'This MCP server provides tools for deep codebase analysis using static analysis and graph generation.\n\n# WHEN TO USE CODEBASE ANALYSIS\n\nProactively use the analyze_codebase tool in these scenarios:\n\n1. EXPLORING NEW CODE: When the user asks about an unfamiliar codebase, analyze it first to understand structure, dependencies, and architecture before answering questions or making changes.\n\n2. PLANNING REFACTORS: Before refactoring code, analyze dependency and call graphs to assess impact across the codebase. Identify all affected files and relationships.\n\n3. ASSESSING CHANGE IMPACT: When asked to modify existing functionality, analyze call graphs to understand what depends on the code being changed.\n\n4. UNDERSTANDING ARCHITECTURE: When questions arise about "how does X work" or "where is Y implemented", analyze the codebase to map out the actual structure and relationships.\n\n5. FINDING DEPENDENCIES: When investigating bugs or adding features, analyze dependency graphs to understand module relationships and potential side effects.\n\n6. MAPPING DOMAIN MODELS: When working with complex business logic, analyze domain classifications to understand system boundaries and architectural patterns.\n\n# QUICK START\n\nBasic workflow:\n1. Create repository ZIP: git archive -o /tmp/repo.zip HEAD\n2. Generate cache key: git rev-parse --short HEAD\n3. Call analyze_codebase with file=/tmp/repo.zip, Idempotency-Key=projectname:supermodel:{hash}, and jq_filter to extract needed data\n4. Use the graph data to inform your work\n5. Keep results in context - reuse for multiple queries about the same code state\n\n# TECHNICAL DETAILS\n\nPREPARING REPOSITORY ZIP FILES:\n\nFor Git Repositories (Recommended):\nRun: cd /path/to/your/repo && git archive -o /tmp/repo.zip HEAD\n\nThis method automatically:\n- Respects .gitignore\n- Includes only tracked files\n- Creates cleaner, smaller archives\n- Produces reproducible results\n\nFor Any Directory:\nRun: cd /path/to/your/repo && zip -r /tmp/repo.zip . -x "node_modules/*" -x ".git/*" -x "dist/*" -x "build/*" -x "target/*" -x "*.pyc" -x "__pycache__/*" -x "venv/*" -x ".venv/*" -x "vendor/*" -x ".idea/*" -x ".vscode/*"\n\nINCLUDE: Source code files (.py, .js, .ts, .tsx, .java, .go, .rs, .rb, .kt, .scala, .c, .cpp, .h, .hpp), configuration files (package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod, pom.xml), and type definitions (.d.ts, .pyi).\n\nEXCLUDE: Dependencies (node_modules/, vendor/, venv/, .venv/, target/), build outputs (dist/, build/, out/, .next/, __pycache__/), version control (.git/), IDE files (.idea/, .vscode/), and large binaries/images/datasets.\n\nIf ZIP exceeds 50MB: Ensure dependencies are excluded, consider analyzing a subdirectory, or check for accidentally committed binary files.\n\nCACHING STRATEGY:\n\nGraph generation is computationally expensive. NEVER regenerate for the same code state.\n\nIdempotency Keys: Use format {repo_identifier}:{graph_type}:{content_hash}\nExample: myproject:supermodel:abc123def\n\nGenerate content hash:\n- For git repos: git rev-parse --short HEAD\n- For ZIP files: shasum -a 256 /tmp/repo.zip | cut -d\' \' -f1 | head -c 12\n\nREGENERATE when:\n- Source code files changed\n- New files added affecting analysis scope\n- Files deleted from the analyzed set\n- Dependencies changed (affects dependency graph)\n\nDO NOT regenerate when:\n- Only documentation/comments changed\n- Only formatting changed\n- Only non-code files changed\n- Switching between different analysis questions on the same code state\n\nSESSION MANAGEMENT:\n\nWithin a session:\n- Keep graph results in context memory\n- Reference previous results instead of re-calling the API\n- Use jq_filter to extract specific subsets from cached results\n- Store summary statistics for quick reference\n\nAcross sessions:\n- Store the idempotency key used\n- Store a summary of the graph (node counts, key relationships)\n- On resume, check if code state matches before regenerating\n\nOPTIMIZATION:\n\nThe analyze_codebase tool returns comprehensive results including all graph types (dependencies, calls, domain model, AST). Call it ONCE and use jq_filter to extract specific data as needed.\n\nExample filters:\n- \'.summary\' - Get overview statistics\n- \'.graph.nodes[] | select(.type=="function")\' - Extract function nodes\n- \'.graph.relationships[] | select(.type=="calls")\' - Extract call relationships\n- \'.graph.nodes[] | select(.file | contains("auth"))\' - Find nodes in auth-related files\n\nTrack: idempotency key, commit/ZIP hash, generation timestamp, summary stats (file count, node count, relationship count).\n\nCOMPLETE EXAMPLE:\n\n# Initial analysis\n$ cd /path/to/project\n$ git archive -o /tmp/project.zip HEAD\n$ HASH=$(git rev-parse --short HEAD)\n# Call analyze_codebase with:\n# file: /tmp/project.zip\n# Idempotency-Key: myproject:supermodel:${HASH}\n# jq_filter: \'.summary\'\n\n# Later queries on same code\n# Reuse cached results or filter differently:\n# jq_filter: \'.graph.nodes[] | select(.type=="class")\'',
|
|
22
22
|
});
|
|
23
23
|
const config = new sdk_1.Configuration({
|
|
24
24
|
basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',
|
|
@@ -13,8 +13,8 @@ exports.metadata = {
|
|
|
13
13
|
operationId: 'generateSupermodelGraph',
|
|
14
14
|
};
|
|
15
15
|
exports.tool = {
|
|
16
|
-
name: '
|
|
17
|
-
description: "
|
|
16
|
+
name: 'analyze_codebase',
|
|
17
|
+
description: "Analyze code structure, dependencies, and relationships across a repository.\n\nUSE THIS TOOL WHEN:\n- Exploring an unfamiliar codebase to understand its architecture\n- Planning refactorings or assessing change impact across multiple files\n- Finding dependencies between modules, functions, or classes\n- Understanding call relationships and code flow patterns\n- Mapping domain models and system boundaries\n- Investigating how components interact before making changes\n\nPROVIDES:\nComprehensive code graphs including:\n- Module and package dependency relationships\n- Function-level call hierarchies\n- Domain classifications and architectural patterns\n- AST-level structural relationships\n- Summary statistics (file counts, languages, complexity)\n\nREQUIRES:\n- file: Path to a ZIP archive of the repository (use `git archive -o /tmp/repo.zip HEAD` for git repos)\n- Idempotency-Key: Cache key in format {repo}:{type}:{hash} (e.g., myproject:supermodel:abc123)\n- jq_filter (optional but recommended): Filter to extract specific data and reduce response size\n\nALWAYS use jq_filter to extract only the data you need. The full response can be very large.\n\nExample filters:\n- '.graph.nodes[] | select(.type==\"function\")' - Extract only function nodes\n- '.summary' - Get just the summary statistics\n- '.graph.relationships[] | select(.type==\"calls\")' - Extract call relationships",
|
|
18
18
|
inputSchema: {
|
|
19
19
|
type: 'object',
|
|
20
20
|
properties: {
|
|
@@ -24,11 +24,12 @@ exports.tool = {
|
|
|
24
24
|
},
|
|
25
25
|
'Idempotency-Key': {
|
|
26
26
|
type: 'string',
|
|
27
|
+
description: 'Cache key in format {repo}:{type}:{hash}. Generate hash with: git rev-parse --short HEAD',
|
|
27
28
|
},
|
|
28
29
|
jq_filter: {
|
|
29
30
|
type: 'string',
|
|
30
31
|
title: 'jq Filter',
|
|
31
|
-
description: 'A jq filter to
|
|
32
|
+
description: 'A jq filter to extract specific fields from the response. STRONGLY RECOMMENDED to reduce response size.',
|
|
32
33
|
},
|
|
33
34
|
},
|
|
34
35
|
required: ['file', 'Idempotency-Key'],
|