pi-shazam
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"pi-shazam": {
"args": [
"-y",
"-p",
"pi-shazam@latest",
"pi-shazam-mcp"
],
"command": "npx"
}
}
}
可用工具 (9 个)
该服务在 MCP 协议中暴露的工具,AI 可按需调用
shazam_overview 3 个参数
When you first enter a project or return after changes - use this to understand the codebase before reading a single file. Returns module dependency map, top-10 PageRank files, key dependencies, recent git changes, entry points, reading order, HTTP routes, and complexity hotspots ranked by blast radius.
该工具无需必填参数,直接调用即可
shazam_lookup 7 个参数 需填 1 项
Look up anything in the codebase - a symbol by name or a file by path. Auto-detects whether the input is a file path or symbol name and returns the most relevant information: definition, kind, signature, type hierarchy, file structure, PageRank, callers/callees. Use mode=state for enum/state analysis. Pass showCallbacks=true to expand anonymous functions.
必填参数:name
shazam_impact 9 个参数
Required before editing 2+ files or any shared/exported module. Returns every file, symbol, and test affected by your planned changes. Pass --symbol for per-symbol caller/callee tracing. Pass --flat for a flat list of references. Pass --direction to filter by incoming/outgoing/both. Pass --with-symbols for per-symbol risk breakdown. Pass --compact for concise output. Pass --depth to control BFS traversal depth (default 3).
该工具无需必填参数,直接调用即可
shazam_verify 9 个参数
After every write or edit, run this to confirm no errors were introduced. Runs LSP diagnostics (type errors, warnings), then graph analysis (git diff, risk level, orphan detection, graph diffs). Verdict: PASS / WARN / FAIL. Use --quick for a fast git-change-only check (~2s). Use --lspOnly for diagnostics only. Use --preCommit for stricter thresholds.
该工具无需必填参数,直接调用即可
shazam_changes 2 个参数
Without this, you optimize the wrong files. Returns a concise summary of what changed in the working tree: changed files, affected symbols, risk level, and which callers may be impacted. Use after edits to see the blast radius before running full verification.
该工具无需必填参数,直接调用即可
shazam_format 4 个参数
When shazam_verify reports format or lint errors, use this to auto-fix them. Runs nearest-wins formatters (prettier, biome, eslint --fix, ruff, cargo fmt, gofmt). Format only - never touches logic. Use --dry-run to preview when unsure.
该工具无需必填参数,直接调用即可
shazam_find_tests 4 个参数
When adding tests or modifying source code - use this to discover which test files already cover a module, what test functions exist, and where new tests belong. Understands conventions for JS/TS (*.test.ts, *.spec.ts), Python (test_*.py / *_test.py), Go (*_test.go), Rust (test_*.rs / *_test.rs), Java (Test*.java / *Test.java), and C# (Test*.cs / *Test.cs). Pass sourceFile or module to scope the search.
该工具无需必填参数,直接调用即可
shazam_rename_symbol 5 个参数 需填 2 项
Required safety gate before renaming any symbol. Step 1: call shazam_impact --symbol to review all references. Step 2: use this to perform the project-wide rename via LSP textDocument/rename. Step 3: call shazam_verify to confirm no broken references. This is a WRITE operation - do not manually find-and-replace; missed references become bugs.
必填参数:symbol、newName
shazam_safe_delete 4 个参数 需填 1 项
Required safety gate before removing any symbol. Automatically verifies zero incoming references before providing deletion instructions. READ-ONLY safety check; returns deletion guidance, does not delete. Do not delete based on intuition - a symbol that looks unused may be called dynamically.
必填参数:symbol
服务介绍
pi-shazam
pi-shazam is a pi-coding-agent native codebase awareness extension. After installation, your agent gains 9 structural analysis tools powered by tree-sitter and LSP — project overviews, symbol lookups, blast radius analysis, verification gates, and more.
Installation
Recommended: pi install (auto-discover)
pi install npm:pi-shazam
Add config to package.json:
{
"pi": {
"extensions": ["./dist"]
}
}
Alternative: Manual Link
git clone https://github.com/gjczone/pi-shazam.git
cd pi-shazam
npm install --legacy-peer-deps && npm run build
ln -s "$(pwd)/dist" ~/.pi/agent/extensions/pi-shazam
MCP (Cursor, Claude Desktop, Windsurf, etc.)
npx pi-shazam-mcp
Configure in your MCP client's settings to use the pi-shazam-mcp command as the MCP server.
Registered Tools
| Tool Name | Trigger | Function |
|---|---|---|
| shazam_overview | First entry, need project structure | Project structure summary, top files by PageRank, dependencies, complexity hotspots |
| shazam_lookup | Need symbol or file details | Unified symbol/file lookup with hover info, type hierarchy, callers/callees |
| shazam_impact | Before editing shared/exported modules | Blast radius analysis — every file, symbol, and test affected by planned changes |
| shazam_verify | After every write or edit | Post-edit verification gate — LSP diagnostics, graph analysis, PASS/WARN/FAIL verdict |
| shazam_changes | After edits to see what changed | Git change summary with symbol-level detail, risk level, affected callers |
| shazam_format | When shazam_verify reports format errors | Auto-fix formatting (prettier, biome, eslint, ruff, cargo fmt, gofmt) |
| shazam_find_tests | Adding tests or modifying source | Discover test files, test functions, and where new tests belong |
| shazam_rename_symbol | Before renaming any symbol | LSP cross-file symbol rename with atomic writes — safety gate enforced |
| shazam_safe_delete | Before removing any symbol | READ-ONLY check for zero incoming references before deletion |
Commands
| Command | Function |
|---|---|
| /shazam-setup | Detect and report LSP server availability with install instructions |
| /shazam-doctor | Health check: tree-sitter grammars, LSP servers, cache integrity |
| /shazam-install-git-hooks | Install git pre-commit hook that runs shazam_verify |
| /shazam-remove-git-hooks | Remove the shazam git pre-commit hook |
| /shazam-pre-commit-verify | Run pre-commit verification (used by git hook) |
Supported Languages
| Language | Tree-sitter | LSP |
|---|---|---|
| Python | Yes | pyright / pylsp |
| TypeScript | Yes | typescript-language-server |
| JavaScript | Yes | typescript-language-server |
| Go | Yes | gopls |
| Rust | Yes | rust-analyzer |
| Dart | Yes | dart language-server |
| JSON | Yes | vscode-json-language-server |
| YAML | - | yaml-language-server |
Platform Support
| Platform | Status |
|---|---|
| Linux | Supported |
| macOS | Supported |
| Windows | Not supported (tree-sitter native bindings) |
Contributing
Development guide see AGENTS.md, release process see rules/OPS.md.