Scantool - File Scanner MCP

Scantool:Claude的代码分析MCP服务器

](https://pypi.org/project/scantool/) 

MCP服务器，用于分析20多种语言的源代码结构。使用 克劳德代码, 克劳德桌面，以及任何 模型上下文协议 客户。由...驱动 树保姆.提取具有精确行号的类、函数、方法、导入、调用图和热函数。

快速开始

需要 紫外线 （提供 uvx 命令）。如果没有它，请先安装它——没有它，scantool将无法启动：

# macOS / Linux / WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

克劳德代码

claude mcp add scantool -- uvx scantool

就是这样。重新启动Claude Code，您就可以开始了。

克劳德桌面

添加到配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "scantool": {
      "command": "uvx",
      "args": ["scantool"]
    }
  }
}

配置后重新启动Claude Desktop。

故障排除： uvx 未找到

uvx 附带 紫外线Python包管理器。先安装：

# macOS / Linux / WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装uv后，重新启动终端 （或打开一个新的） uvx 在你的路径上。然后重新运行上面的setup命令。

如果 uvx 重启终端后仍未找到，请手动将其添加到PATH中：

# Linux / WSL - add to ~/.bashrc or ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"

# macOS - usually works out of the box, but if not:
export PATH="$HOME/.local/bin:$PATH"

替代方案：从源代码安装

git clone https://github.com/mariusei/file-scanner-mcp.git
cd file-scanner-mcp
uv sync

# Claude Code
claude mcp add --transport stdio scantool -- uv run --directory /path/to/file-scanner-mcp scantool

# Claude Desktop
# Use command: "uv", args: ["run", "--directory", "/path/to/file-scanner-mcp", "scantool"]

与您的团队共享（.mcp.json）

添加a .mcp.json 将文件保存到项目根目录，以便与团队共享配置：

{
  "mcpServers": {
    "scantool": {
      "command": "uvx",
      "args": ["scantool"]
    }
  }
}

Claude Code将在首次使用时提示团队成员批准。

特性

多语言支持

Python、JavaScript、TypeScript、Rust、Go、C/C++、Java、PHP、C#、Ruby、Zig、Swift、SQL（PostgreSQL、MySQL、SQLite）、HTML、CSS、SCSS、Markdown、纯文本、图像

结构提取

• 类、方法、函数、导入
• 带有类型注释的函数签名
• 装饰者和属性
• 文档字符串和JSDoc注释
• 精确的行号（从到范围）

分析工具

• 预览目录：具有入口点、导入图、调用图和热函数的智能代码库分析（5-10s）
• 扫描文件：包含签名和元数据的详细文件结构
• scan_directory：具有内联函数/类名的紧凑目录树
• 搜索结构：按类型、名称模式、装饰器或复杂性过滤
• list_目录：目录树（仅文件夹）

输出格式

• 带方框图字符的树形格式
• 用于编程的JSON格式
• 可配置的显示选项

用法

preview_directory-代码分析（主要工具）

分析代码库结构，包括入口点、导入图、调用图和热函数。

preview_directory(
    directory=".",
    depth="deep",             # "quick", "normal", or "deep" (default: "deep")
    max_files=10000,          # Safety limit (default: 10000)
    max_entries=20,           # Entries per section (default: 20)
    respect_gitignore=True    # Honor .gitignore (default: True)
)

深度级别：

• "quick"：仅元数据（0.5秒）-文件计数、大小、类型
• "normal"：架构分析（2-5s）-导入、入口点、集群
• "deep"：完整分析（5-10s）-包括热函数和调用图（默认）

示例输出（深度=“deep”）：

project/

--- ENTRY POINTS ---
  main.py:main() @1
  backend/application.py:Flask app @15
  frontend/index.ts:export default

--- CORE FILES (by centrality) ---
  backend/database.py: imports 0, used by 15 files
  backend/auth.py: imports 1, used by 8 files
  shared/utils.py: imports 2, used by 12 files

--- ARCHITECTURE ---
  Entry Points: 25 files
  Core Logic: 68 files
  Plugins: 15 files
  Tests: 42 files

--- HOT FUNCTIONS (most called) ---
  get_database() (function): called by 41, calls 1 @backend/database.py
  authenticate() (function): called by 23, calls 5 @backend/auth.py
  validate_input() (function): called by 15, calls 2 @shared/utils.py

Analysis: 486 files in 4.82s (layer1+layer2)

使用案例：

• 首次代码库探索
• 了解多模态项目（前端/后端/数据库）
• 查找关键功能（热点）
• 确定切入点

scan_file-详细的文件分析

scan_file(
    file_path="path/to/file.py",
    show_signatures=True,      # Include function signatures with types
    show_decorators=True,      # Include @decorator annotations
    show_docstrings=True,      # Include first line of docstrings
    show_complexity=False,     # Show complexity metrics
    output_format="tree"       # "tree" or "json"
)

输出示例：

example.py (1-57)
├─ file-info: 1.4KB modified: 2 hours ago
├─ imports: import statements (3-5)
├─ class: DatabaseManager (8-26)
│    "Manages database connections and queries."
│  ├─ method: __init__ (self, connection_string: str) (11-13)
│  ├─ method: connect (self) (15-17)
│  │    "Establish database connection."
│  └─ method: query (self, sql: str) -> list (24-26)
│       "Execute a SQL query."
└─ function: main () (53-57)
     "Main entry point."

scan_file_content-直接分析内容

无需文件路径即可扫描内容。适用于远程文件、API或内存中的内容。

scan_file_content(
    content="def hello(): pass\n\nclass MyClass:\n    pass",
    filename="example.py",     # Extension determines parser
    show_signatures=True,
    show_decorators=True,
    show_docstrings=True,
    show_complexity=False,
    output_format="tree"
)

scan_directory-简明概述

显示具有内联类/函数名称的目录树。

scan_directory(
    directory="./src",
    pattern="**/*",                 # Glob pattern
    max_files=None,                 # File limit
    respect_gitignore=True,         # Honor .gitignore
    exclude_patterns=None,          # Additional exclusions
    output_format="tree"            # "tree" or "json"
)

输出示例：

src/ (22 files, 15 classes, 127 functions, 89 methods)
├─ languages/
│  ├─ python.py (1-329) [11.9KB, 2 hours ago] - PythonLanguage
│  ├─ typescript.py (1-505) [18.9KB, 1 day ago] - TypeScriptLanguage
│  └─ rust.py (1-481) [17.6KB, 3 days ago] - RustLanguage
├─ scanner.py (1-232) [8.8KB, 5 mins ago] - FileScanner
└─ server.py (1-735) [27.2KB, just now] - scan_file, scan_directory, ...

模式示例：

# Specific file types
scan_directory("./src", pattern="**/*.py")

# Multiple types
scan_directory("./src", pattern="**/*.{py,ts,js}")

# Shallow scan (1 level deep)
scan_directory(".", pattern="*/*")

# Exclude directories
scan_directory(".", exclude_patterns=["tests/**", "docs/**"])

search_structures-查找和筛选

# Find test functions
search_structures(
    directory="./tests",
    type_filter="function",
    name_pattern="^test_"
)

# Find classes ending in "Manager"
search_structures(
    directory="./src",
    type_filter="class",
    name_pattern=".*Manager$"
)

# Find functions with @staticmethod
search_structures(
    directory="./src",
    has_decorator="@staticmethod"
)

# Find complex functions (>100 lines)
search_structures(
    directory="./src",
    type_filter="function",
    min_complexity=100
)

list_directories-文件夹结构

显示没有文件的目录树。

list_directories(
    directory=".",
    max_depth=3,              # Maximum depth (default: 3)
    respect_gitignore=True    # Honor .gitignore (default: True)
)

输出示例：

/Users/user/project/
├─ src/
│  ├─ components/
│  ├─ services/
│  └─ utils/
├─ tests/
│  ├─ unit/
│  └─ integration/
└─ docs/

支持的语言

所有文件都自动包含元数据（大小、修改日期、权限）。

用例

代码导航

• 不熟悉代码库的结构概述
• 文件组织理解
• 使用精确的线条范围进行导航

重构

• 确定安全拆分的类和函数边界
• 查找特定模式的实现
• 将功能定位在复杂性阈值之上

代码审查

• 产生结构性差异
• 查找具有特定装饰器的函数
• 识别测试覆盖率差距

文档

• 自动生成带有行号的目录
• 提取API签名
• 将结构化数据馈送到分析工具（JSON输出）

AI代码辅助

• 主要探索工具（取代ls/grep/find工作流）
• 为LLM上下文窗口智能分区大文件
• 提取具有精确边界的代码段
• 跨代码库搜索模式
• 减少令牌使用：先获取结构，只在需要时读取内容

建筑

scantool/
├── server.py        # FastMCP server (stdio + HTTP entry points)
├── scanner.py       # Core scanning logic using tree-sitter
├── formatter.py     # Tree formatting with box-drawing characters
├── code_map.py      # Architecture analysis (Layer 1 + 2)
├── call_graph.py    # Hot functions, centrality analysis
├── preview.py       # Quick directory preview
└── languages/       # Unified language system (one file per language)
    ├── base.py      # BaseLanguage - all languages inherit from this
    ├── models.py    # StructureNode, CallInfo, ImportInfo, etc.
    ├── python.py    # PythonLanguage
    ├── typescript.py
    ├── rust.py
    └── ...          # 20+ languages

HTTP传输（高级）

对于stdio不起作用的环境，或者在多个客户端之间共享服务器时：

# Start the HTTP server
uvx --from scantool scantool-http
# Listens on port 8080 by default (set PORT env var to change)

# Connect Claude Code to it
claude mcp add --transport http scantool http://127.0.0.1:8080/mcp

注意：HTTP服务器必须单独启动并保持运行。对于大多数用户来说，stdio传输（默认）更简单，建议使用。

测试

# Run all tests
uv run pytest

# Run specific tests
uv run pytest tests/languages/
uv run pytest tests/python/
uv run pytest tests/typescript/

# Run with coverage
uv run pytest --cov=src/scantool

# Run with verbose output
uv run pytest -v

贡献

看 贡献.md 有关添加语言支持的详细信息。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

依赖项

• FastMCP -MCP服务器框架
• 树保姆 -解析库
• 紫外线 -Python包安装程序

已知限制

MCP工具响应大小限制

Claude Desktop对MCP工具的响应实施了25000个令牌的限制。Claude Code有一个可配置的限制（设置 MAX_MCP_OUTPUT_TOKENS 要调整的env变量）。

内置缓解措施：

• scan_directory() 使用紧凑的内联格式
• 尊重 .gitignore 默认情况下（不包括node_modules、.vev等）
• 显示具有相对时间戳的文件元数据

手动控制：

• 使用 pattern 限制范围： "**/*.py" 对比 "*/*" （浅）
• 使用 max_files 限制处理的文件数量
• 使用 exclude_patterns 其他除外责任
• 扫描特定的子目录，而不是整个代码库

对于大型代码库：

# Scan specific areas
scan_directory("./src", pattern="**/*.py")
scan_directory("./tests", pattern="**/*.py")

代理委托

使用Claude Code时，要求“探索代码库”可能会委托给无法访问MCP工具的explore代理。明确：“使用scantool扫描代码库”，以确保直接使用MCP工具。

支持

-