AI Dev Toolkit - MCP Server

• 集成架构：将所有功能整合到一个 AI Librarian 服务中 （稳定：Code，预 Beta：Desktop）
• 简化设置：一步安装到 Claude Desktop/Code （稳定：Code，Beta：Desktop）
• 性能优化：降低开销，加快响应速度 （稳定）
• 完全符合 MCP 规范：完整实现模型上下文协议标准 （稳定：Desktop）
• 工具索引集成：提供针对 AI 优化的工具选择和使用指导 （稳定）

• 代码理解：全面索引代码库并跟踪组件 （稳定）
• 持久化上下文：在多轮对话中持续了解代码结构 （稳定）
• 组件关系分析：自动检测依赖关系和关联 （稳定）
• 文档生成：提取文档字符串并创建文档 （稳定）
• 实时更新：自动监控项目变更，保持信息最新 （稳定）
• 迷你图书管理员：将大型代码库拆分为专门的知识单元，以便进行管理 （稳定：Code，Beta：Desktop）

• 自动集成：无需手动设置——只需初始化，一切便会自动运行 （稳定）
• 代码与工具桥接：智能地将代码组件与相关工具连接起来 （稳定）
• 双向引用：可以在组件与工具之间双向导航 （稳定）
• 上下文感知：了解哪些工具最适用于特定代码 （稳定）
• 后台维护：随着代码演进，持续更新交叉引用 （稳定）

• 安全访问项目：受控访问开发文件 （稳定）
• 目录导航：直观地浏览和探索目录 （稳定）
• 代码操作：读取、写入和修改代码，并妥善处理错误 （稳定）
• 增强型文件编辑：改进文件编辑功能，提供更好的错误处理和预览 （稳定）
• 编辑书签：为复杂代码段编辑创建、编辑和应用书签 （稳定）
• 书签管理：列出、检索和更新多部分编辑所用的书签 （稳定）
• 文件操作：全面的文件管理功能 （稳定）
• 搜索与索引：使用强大的搜索工具查找文件和内容 （稳定）
• Git 仓库跟踪：分析和跟踪 Git 仓库及其历史记录 （稳定）

• 异步处理：在后台执行长时间运行的操作 （稳定）
• 优先级任务队列：按优先级管理操作，并自动设置超时 （稳定）
• 后台工作线程：使用工作线程池并行执行任务 （稳定）
• 任务持久化：服务器重启后操作仍会保留，并自动恢复 （稳定）
• Think 工具：为复杂问题提供深入的分析推理能力 （稳定）
• 进度跟踪：监控任务状态、结果和执行指标 （稳定）
• 跨组件集成：在所有子系统中统一处理任务 （稳定）

• 持久化待办跟踪：任务会在不同对话间保留 （稳定）
• 多层级任务结构：支持任务、子任务和依赖关系 （稳定）
• 优先级与状态跟踪：按重要程度和完成状态组织工作 （稳定）
• 代码上下文关联：将任务与特定代码组件关联 （稳定）
• 自动推断任务：从对话中提取潜在任务 （稳定：Code，Beta：Desktop）

• 漏洞评估：以专业水准对代码库进行安全分析 （稳定）
• 基于模式的扫描：检测常见安全漏洞 （稳定）
• 基于 AST 的分析：通过高级代码分析发现安全问题 （稳定）
• 严重程度分类：按严重程度对问题进行分类（从严重到信息级） （稳定）
• 标准化报告：提供 CWE ID 和详细的漏洞说明 （稳定）
• AI Toolkit 专属模式：为 AI Dev Toolkit 组件定制规则 （稳定）
• 与 Sanity Check 集成：结合代码质量与安全评估 （稳定）
• 独立安全工具：可通过 security_analyze() 函数独立使用 （稳定）

• AI 小型图书管理员：专门处理特定分析任务的 AI Agent（稳定版）
• 异步处理：在后台处理复杂操作（稳定版）
• 任务队列管理：按优先级执行任务，并处理超时（稳定版）
• 可靠运行：从故障和超时中自动恢复（稳定版）
• 面向 AI 优化的简写格式：采用压缩格式，实现高效的 AI 间通信（稳定版：Code，测试版：Desktop）
• 高级上下文感知：丰富的上下文信息将任务与代码关联起来（稳定版）
• 分布式知识系统：将智能分布于各个专用 Agent（稳定版：Code，测试版：Desktop）

• 结构化反思：Claude 用于推理复杂问题的草稿区（稳定版）
• 需求验证：检查是否已收集所有必需信息（稳定版）
• 规则合规性检查：验证计划中的操作是否符合策略（稳定版）
• 详细规划：将复杂任务分解为易于管理的步骤（稳定版）
• 结果分析：处理并验证其他工具的结果（稳定版）
• 明确区分：将内部思考过程与用户对话分开（稳定版）
• 决策支持：比较不同方案并选择最佳选项（稳定版）

• MCP 提示词：为常见任务预定义的对话模板（稳定版）
  • analyze-codebase：全面分析项目
  • debug-issue：调试协助工作流
  • refactor-code：代码重构指导
  • add-feature：功能实现工作流
• 动态资源：通过 MCP 资源访问项目元数据（测试版）
  • librarian://projects/*：项目元数据和 AI Librarian 数据
  • librarian://bookmarks/*：编辑书签信息
  • librarian://diagnostics/*：诊断信息
• 提示词工具：为复杂任务动态生成指导（稳定版）
  • get_debugging_guide：根据上下文提供调试协助
  • get_refactoring_guide：针对特定类型的重构策略
  • get_feature_implementation_guide：功能开发工作流
  • get_analysis_guide：代码库分析方法

重要提示：以下所有代码示例都展示了 Claude 如何在内部使用这些工具。这些都不是你需要执行的命令——Claude 会自动处理一切！

优化工具使用，避免超时

为确保最佳性能并防止超时，Claude 遵循以下分层工具选择准则：

分层工具选择

Claude 按以下顺序优先选择工具：

1. 优先检查组件注册表：在执行文件系统操作前，检查 .ai_reference/component_registry.json
2. 其次检查脚本索引：使用 .ai_reference/script_index.json 查找特定文件
3. 最后执行直接文件操作：仅在无法获取索引数据时，才将其作为最后手段

# PREFERRED: Query component registry directly (fastest)
registry_path = f"{project_path}/.ai_reference/component_registry.json"
with open(registry_path, 'r') as f:
    registry = json.load(f)
component = registry["components"].get(component_name)

# If found, do targeted file reading
if component:
    file_path = component["primary_file"]
    # Now read just this specific file

代码搜索

# PREFERRED: Use script index to identify exact files to check
index_path = f"{project_path}/.ai_reference/script_index.json"
with open(index_path, 'r') as f:
    script_index = json.load(f)

# Find files containing target class/function
matches = []
for file_path, info in script_index["files"].items():
    if target_name in info["classes"] or target_name in info["functions"]:
        matches.append(file_path)
        
# Read only those specific files

长时间运行的操作

# Use TaskBoard for operations that might time out
task_id = submit_background_task(
    task_type="search",
    target_path=project_path,
    pattern=search_pattern
)
# Check status and get results when ready
task_result = get_task_result(task_id)

AI 图书管理员与统一上下文

当你要求 Claude 了解、分析或浏览代码库时，它会在幕后使用以下函数：

# Initialize AI Librarian for a project
# This one command sets up everything - AI Librarian, Unified Context, and Tool References
initialize_enhanced_librarian("path/to/your/project")

# Search for code implementations
find_implementation("path/to/your/project", "login function")

# Query components
query_component("path/to/your/project", "MyClass")

# Find tools related to a specific component
find_related_tools("path/to/your/project", "AuthenticationManager")

# Find components related to a specific tool
find_related_components("path/to/your/project", "edit_file")

# Get a unified view of your project
get_unified_context("path/to/your/project")

大型代码库支持

对于较大的代码库，Claude 会使用迷你图书管理员，以便高效浏览和理解代码库：

# Access mini-librarians directly (Claude Code)
read_file(".ai_reference/scripts/___aitoolkit_librarian_ai_dev_toolkit_py.json")

# Get component information from mini-librarians
get_component_details("path/to/project", "ComponentName") 

# Search across mini-librarians
search_mini_librarians("path/to/project", "function_name")

任务管理

当你要求 Claude 跟踪任务时，它会在内部使用以下函数：

# Add a task
add_todo("path/to/project", "Implement login feature", priority="high")

# List tasks
list_todos("path/to/project")

# Update task status
update_todo_status("path/to/project", "todo-123", "completed")

高级 AI 任务管理

对于更复杂的任务跟踪，Claude 会使用以下高级函数：

# Create an AI-optimized task
add_ai_task("path/to/project", "Authentication system refactoring", "Improve security and performance", "refactor", 2)

# List AI tasks
list_ai_tasks("path/to/project", status="active", priority=1)

# Add detailed code context to a task
add_task_context(task_id, "code_snippet", "Task relates to authentication system")

Think 工具

处理复杂的推理任务时，Claude 会将 Think 工具用作私有草稿板：

# Use the think tool as a scratchpad for reflection
think("""
User wants to implement a new authentication feature.
- Required information:
  * User roles and permissions structure
  * Current authentication flow
  * Security requirements
- Implementation approach options:
  * Extend existing AuthManager
  * Create new specialized AuthProvider
  * Use third-party authentication library
- Considerations:
  * Performance impact
  * Security implications
  * Maintenance complexity
- Decision:
  * Extending existing AuthManager seems most appropriate
  * Need to add role validation logic
  * Will require unit tests for new functionality
""")

# For deeper, time-consuming analysis, use deep_analysis from the TaskBoard system
task_id = deep_analysis(project_path, "I need to understand how the authentication system works and its dependencies")
get_task_status(project_path, task_id)
get_task_result(project_path, task_id)

文件系统操作

Claude 使用以下函数处理项目文件：

# Read a file
read_file("path/to/your/file.py")

# Write to a file
write_file("path/to/your/file.py", "file content")

# Edit bookmarks for complex code changes
bookmark_id = create_edit_bookmark("path/to/project", "path/to/file.py", 10, 25)
update_bookmark("path/to/project", bookmark_id, "new content for lines 10-25")
apply_bookmark("path/to/project", bookmark_id)

# List directory contents
list_directory("path/to/your/directory")

# Search for files
search_files("path/to/your/project", "pattern")

# Git repository tracking
git_info = get_git_info("path/to/your/project")
update_git_history("path/to/your/project", ".git_history")

# Project upgrading and analysis
from aitoolkit.utils.upgrade_manager import UpgradeManager

# Check if a project needs an upgrade
needs_upgrade, current, latest = UpgradeManager.needs_upgrade("path/to/project")

# Analyze a project structure and get recommendations
analysis = UpgradeManager.analyze_project("path/to/project")
recommendations = analysis["recommendations"]["recommendations"]

# Upgrade a project to the latest version
results = UpgradeManager.upgrade("path/to/project", backup=True)

# Or use the command-line tool
# python scripts/upgrade_ai_toolkit.py --analyze /path/to/project
# python scripts/upgrade_ai_toolkit.py /path/to/project

Claude Code 与桌面应用功能对比

Claude Code 可以通过迷你图书管理员和适配器模式来模拟工具包功能：

Claude Code 适配器模式

Claude Code 通过存储在 .ai_reference 目录中的适配器模式模拟工具包功能：

# Example: Instead of direct toolkit call like:
result = create_edit_bookmark("path/to/project", "path/to/file.py", 10, 25)

# Claude Code reads the adapter pattern and executes:
file_content = read_file("path/to/file.py")
content_to_edit = file_content.splitlines()[10:25]
# Store in memory for later application
session_bookmarks["bookmark1"] = {"file": "path/to/file.py", "start": 10, "end": 25, "content": content_to_edit}

安全分析

对于安全分析任务，Claude 会在内部使用以下函数：

# Run a comprehensive security analysis on your project
security_report = security_analyze("path/to/your/project")

# Enhanced sanity check with security analysis included
check_report = enhanced_sanity_check("path/to/your/project", include_security=True)

优化性能并处理超时

Claude 会自动采用以下优化策略：

# Initialize with robustness features automatically applied
# This is the recommended all-in-one initialization method
initialize_ai_dev_toolkit("path/to/your/project")

# For other long-running operations, robustness decorators are used
from aitoolkit.utils.tool_wrappers import make_robust

@make_robust(timeout=60.0, max_retries=2)
def my_search_function(query):
    # Implementation here

常见问题及解决方案：

• ⚠️ 缺少 MCP - Claude Desktop 无法连接：如果看到“在没有 Claude Desktop 连接的有限功能模式下运行”或类似提示，说明未安装 MCP 软件包。运行以下命令修复：

  pip install mcp[cli]
  

  然后重启服务。详细说明请参阅 MCP_INSTALLATION.md。

• 服务正在运行，但没有 Claude Desktop 连接：请确认：

  1. 已安装 MCP 软件包（pip list | grep mcp）
  2. 服务已正确初始化 MCP 并正在运行
  3. Claude Desktop 配置指向正确的服务路径
  4. 超时设置正确（请参阅 MCP_INSTALLATION.md）

• 工具包未显示在 Claude 中：请确保配置已正确保存，并已重启 Claude Desktop

• 权限错误：检查配置中允许访问的目录

• 连接问题：确认 Claude Desktop 已正确配置，并重启服务

• 导入错误：确保已安装所有依赖项

• 文件访问问题：确认服务拥有访问文件的适当权限

• 健全性检查问题：如果 sanity_check 工具出现问题，请改用 find_implementation() 和 query_component() 等单独的诊断工具

• 旧版文件：回退到先前版本时，在运行 git reset --hard 后使用 git clean -fd，确保移除所有未跟踪的文件

• 重复文件：在清理过程中，可能会遇到扩展名为 .old、.backup、.fixed 等的重复文件；这些问题将在后续版本中处理

• find_related_files 工具错误：此工具存在一个已知问题，将在后续版本中修复

• 超时错误：我们在 0.5.4 版本中改进了超时处理，采用更可靠的基于线程的机制，并延长了搜索和写入操作的超时时间。我们还将 MCP 协议超时时间从 30s 延长至 120s，以防止服务断开连接。如果仍然遇到超时，请尝试运行 python install_for_claude_code.py，将项目升级到最新版本。

• 旧版 .ai_reference 格式：对于包含旧格式 .ai_reference 目录的项目，请运行安装程序 python install_for_claude_code.py，它会自动检测并提示升级这些目录

• 工具超时性能问题：如果工具耗时过长并发生超时，请使用上文“优化工具使用”一节中介绍的分层工具选择方法。执行直接文件系统操作前，务必先查询组件注册表和脚本索引。

更多文档请参阅 docs 目录：

• AI 图书管理员指南
• 任务系统文档
• MCP 服务模板
• 项目结构
• 工具参考
• 升级 AI Reference
• 升级管理器
• Think 工具指南

即将发布

• Beta 版本：即将推出高级 GUI 界面改进
• 代码库清理：整合重复文件和旧版代码
• 健全性检查改进：增强诊断能力和报告功能
• GUI 改进：增强配置器界面并加入清理工具
• 项目模板：为常见项目类型提供入门模板

最近发布

• [0.5.8] GUI 改进（当前版本）：采用增强的现代化界面，支持选择配色模式、自定义字体和调整文本大小。新增专属的「帮助与故障排除」选项卡、带终端功能的「开发者」选项卡，以及支持筛选的按需日志浏览器；同时移除了服务状态监控，以避免干扰 Claude Desktop。
• [0.5.7] GUI 增强：新增 Claude Desktop 进程管理和重启功能、日志筛选系统，并通过更直观的按钮布局改进了仪表板的组织方式。
• [0.5.6] 升级管理器：新增项目分析和升级系统，并集成到 GUI 中；支持清空请求队列，并重新分类了 Think Tool。
• [0.5.5] Git 集成：新增 Git 仓库跟踪和分析功能，并提供新的 MCP 工具，用于获取 Git 信息以及为 Claude 生成历史文件。

未来计划

• IDE 集成：为 VS Code 和其他 IDE 开发扩展
• 高级代码分析：深入理解代码语义
• 团队工作流工具：集成项目管理

当前正在进行的工作

• 工具索引改进：近期已实现简易工具索引系统，性能得到大幅提升：

  • 以单次遍历架构取代复杂的多阶段处理
  • 直接发现函数，无需处理子进程
  • 执行速度最高提升 10 倍（不到 5 秒，而此前需要 60 多秒）
  • 减少故障点，提高可靠性
  • 简化输出格式，提升可维护性

• 完整性检查与安全分析：显著改进了 sanity_check 工具：

  • 集成 Security Analyzer，进行全面评估
  • 支持严重程度级别（严重、警告、信息）
  • 增强错误处理并修复编码问题
  • 提供带 CWE ID 的专业安全评估
  • 基于 AST 进行分析，以深入理解代码
  • 改进报告，提供结构化输出

• 目录结构清理：持续整合功能重叠的部分：

  • 整合 librarian 目录中的重复文件：
    • 合并增强型文件编辑功能
    • 统一各模块的命名规范
    • 移除已弃用的功能（基础索引器已由 enhanced_indexer 取代）
  • 清理 gui 目录：
    • 统一使用 configurator_new.py 作为主要 GUI 实现
    • 删除旧版文件和备份文件
    • 添加用于清理旧版文件的 GUI 按钮

• 文件系统操作：增强文件编辑和处理功能

• 稳健性改进：增强超时和重试处理：

  • 为长时间运行的操作添加自动重试机制
  • 改进队列管理，避免请求冲突
  • 提供性能指标以识别瓶颈
  • 通过可配置阈值改进超时处理