AI Dev Toolkit - MCP Server

• Integrated Architecture: All capabilities consolidated in one AI Librarian server (Stable: Code, Pre-Beta: Desktop)
• Simplified Setup: One-step installation to Claude Desktop/Code (Stable: Code, Beta: Desktop)
• Optimized Performance: Reduced overhead and faster response times (Stable)
• Full MCP Compliance: Complete implementation of Model Context Protocol standards (Stable: Desktop)
• Tool Index Integration: AI-optimized tool selection and usage guidance (Stable)

• Code Understanding: Comprehensive codebase indexing with component tracking (Stable)
• Persistent Context: Code structure awareness persists across conversations (Stable)
• Component Relationship Analysis: Automatically detects dependencies and relationships (Stable)
• Documentation Generation: Extracts docstrings and creates documentation (Stable)
• Real-time Updates: Monitors project changes automatically to stay current (Stable)
• Mini-Librarians: Handle large codebases by breaking them into specialized knowledge units (Stable: Code, Beta: Desktop)

• Automatic Integration: Zero manual setup - just initialize and everything works (Stable)
• Code-Tool Bridging: Intelligently connects code components to relevant tools (Stable)
• Bidirectional References: Navigate from components to tools and vice versa (Stable)
• Context Awareness: Understands which tools are most useful for specific code (Stable)
• Background Maintenance: Continuously updates cross-references as code evolves (Stable)

• Reference Finding: Locate all references to components across the codebase (Stable)
• Pattern Detection: Identify common patterns and anti-patterns (Stable)
• File Overview: Comprehensive analysis of file structure with metrics (Stable)
• Component Details: Rich component information with examples and documentation (Stable)
• Usage Context: Understand how components are used throughout the project (Stable)
• Large Codebase Support: Efficient handling of multi-module projects via mini-librarians (Stable: Code, Beta: Desktop)

• Secure Project Access: Controlled access to your development files (Stable)
• Directory Navigation: Intuitive directory navigation and exploration (Stable)
• Code Manipulation: Read, write, and modify code with proper error handling (Stable)
• Enhanced Edit File: Improved file editing with better error handling and preview (Stable)
• Edit Bookmarks: Create, edit, and apply bookmarks for complex code section edits (Stable)
• Bookmark Management: List, retrieve, and update bookmarks for multi-part edits (Stable)
• File Operations: Comprehensive file management capabilities (Stable)
• Search & Indexing: Find files and content with powerful search tools (Stable)
• Git Repository Tracking: Analyze and track git repositories and their history (Stable)

• Asynchronous Processing: Execute long-running operations in the background (Stable)
• Prioritized Task Queue: Manage operations by priority with automatic timeouts (Stable)
• Background Workers: Pool of worker threads for parallel task execution (Stable)
• Task Persistence: Operations survive server restarts with automatic recovery (Stable)
• Think Tool: Deep analytical reasoning capabilities for complex problems (Stable)
• Progress Tracking: Monitor task status, results and execution metrics (Stable)
• Cross-component Integration: Unified task processing across all subsystems (Stable)

• Persistent To-Do Tracking: Tasks persist across conversations (Stable)
• Multi-level Task Structure: Support for tasks, subtasks, and dependencies (Stable)
• Priority & Status Tracking: Organize work by importance and completion status (Stable)
• Code Context Linking: Associate tasks with specific code components (Stable)
• Automatic Task Inference: Extract potential tasks from conversations (Stable: Code, Beta: Desktop)

• Vulnerability Assessment: Professional-level security analysis of codebases (Stable)
• Pattern-based Scanning: Detection of common security vulnerabilities (Stable)
• AST-based Analysis: Sophisticated code analysis for security issues (Stable)
• Severity Classification: Issues categorized by criticality (Critical to Info) (Stable)
• Standardized Reporting: CWE IDs and detailed vulnerability descriptions (Stable)
• AI Toolkit-Specific Patterns: Custom rules for AI Dev Toolkit components (Stable)
• Integration with Sanity Check: Combined code quality and security assessment (Stable)
• Independent Security Tool: Can be used standalone with security_analyze() function (Stable)

• Simple, Robust Implementation: Single-pass indexing with no subprocesses for improved reliability and performance (Stable)
• AI-Optimized Tool Profiles: Detailed metadata that helps Claude select the right tools (Stable)
• Asynchronous Tool Indexing: Background processing of tool indexing via TaskBoard integration (Stable)
• Bidirectional References: Cross-references between code components and applicable tools (Stable)
• Component-Tool Mapping: Automatic mapping of which tools work with specific components (Stable)
• Direct Function Discovery: Scans common locations for tool functions and imports/analyzes them directly (Stable)
• Simplified Output Format: Flat, reference-catalog style organization for easy navigation (Stable)
• Metadata Extraction: Uses Python's introspection capabilities for accurate tool information (Stable)

• AI Mini-Librarians: Specialized AI agents that process specific analysis tasks (Stable)
• Asynchronous Processing: Background task processing for complex operations (Stable)
• Task Queue Management: Prioritized task execution with timeout handling (Stable)
• Resilient Operations: Automatic recovery from failures and timeouts (Stable)
• AI-Optimized Shorthand: Compressed format for efficient AI-to-AI communication (Stable: Code, Beta: Desktop)
• Advanced Context Awareness: Rich contextual information links tasks to code (Stable)
• Distributed Knowledge System: Intelligence distributed across specialized agents (Stable: Code, Beta: Desktop)

• Structured Reflection: Claude's scratchpad for reasoning through complex problems (Stable)
• Requirements Verification: Check if all required information is collected (Stable)
• Rule Compliance Checking: Verify if planned actions comply with policies (Stable)
• Detailed Planning: Break down complex tasks into manageable steps (Stable)
• Results Analysis: Process and verify the results of other tools (Stable)
• Clear Separation: Keep internal thought processes separate from user conversation (Stable)
• Decision Support: Compare approaches and select the best option (Stable)

• MCP Prompts: Pre-defined conversation templates for common tasks (Stable)
  • analyze-codebase: Comprehensive project analysis
  • debug-issue: Debugging assistance workflow
  • refactor-code: Code refactoring guidance
  • add-feature: Feature implementation workflow
• Dynamic Resources: Access project metadata through MCP resources (Beta)
  • librarian://projects/*: Project metadata and AI Librarian data
  • librarian://bookmarks/*: Edit bookmark information
  • librarian://diagnostics/*: Diagnostic information
• Prompt Tools: Dynamic guidance generators for complex tasks (Stable)
  • get_debugging_guide: Context-aware debugging assistance
  • get_refactoring_guide: Type-specific refactoring strategies
  • get_feature_implementation_guide: Feature development workflow
  • get_analysis_guide: Codebase analysis approaches

• Automatic Retries: Long-running operations automatically retry on failure (Stable)
• Timeout Handling: Graceful handling of timeouts with configurable limits (Stable)
• Queue Management: Clear stale requests before starting new operations (Stable)
• Performance Tracking: Measure and log execution times for optimization (Stable)
• Error Recovery: Robust error handling with detailed diagnostics (Stable)
• Large Codebase Handling: Efficient processing of large repositories with segmentation (Stable: Code, Beta: Desktop)

Important: All code examples below demonstrate how Claude uses these tools internally. These are NOT commands that you need to execute - Claude handles everything automatically!

Optimized Tool Usage to Avoid Timeouts

To ensure the best performance and prevent timeouts, Claude follows these hierarchical tool selection guidelines:

Hierarchical Tool Selection

Claude prioritizes tools in this order:

1. Component Registry First: Check .ai_reference/component_registry.json before filesystem operations
2. Script Index Second: Use .ai_reference/script_index.json to find specific files
3. Direct File Operations Last: Only as a final resort when indexed data is unavailable

# 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

For Code Searches

# 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

For Long-Running Operations

# 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 Librarian & Unified Context

When you ask Claude to understand, analyze, or navigate your codebase, it's using these functions behind the scenes:

# 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")

Large Codebase Support

For larger codebases, Claude uses mini-librarians to provide efficient navigation and understanding:

# 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")

Task Management

When you ask Claude to track tasks, it uses these functions internally:

# 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")

Advanced AI Task Management

For more sophisticated task tracking, Claude uses these advanced functions:

# 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 Tool

When handling complex reasoning tasks, Claude uses the Think Tool as a private scratchpad:

# 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)

File System Operations

Claude uses these functions to work with your project files:

# 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 vs Desktop Functionality

Claude Code can simulate toolkit functionality through mini-librarians and adapter patterns:

Claude Code Adapter Patterns

Claude Code simulates toolkit functionality through adapter patterns stored in the .ai_reference directory:

# 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}

Security Analysis

For security analysis tasks, Claude uses these functions internally:

# 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)

Optimizing Performance and Handling Timeouts

Claude automatically implements these optimization strategies:

# 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

Common issues and solutions:

• ⚠️ MCP Missing - Claude Desktop Cannot Connect: If you see "Running in limited functionality mode without Claude Desktop connection" or similar, the MCP package is not installed. Fix with:

  pip install mcp[cli]
  

  Then restart the server. See MCP_INSTALLATION.md for detailed instructions.

• Server Runs But No Claude Desktop Connection: Verify that:

  1. MCP package is installed (pip list | grep mcp)
  2. Server is running with proper MCP initialization
  3. Claude Desktop config points to correct server path
  4. Timeout settings are correct (see MCP_INSTALLATION.md)

• Toolkit Not Appearing in Claude: Ensure configuration was saved correctly and Claude Desktop was restarted

• Permission Errors: Check allowed directories in the configuration

• Connection Issues: Verify Claude Desktop is properly configured and restart the server

• Import Errors: Make sure all dependencies are installed

• File Access Problems: Verify the server has appropriate permissions to access your files

• Sanity Check Issues: If experiencing problems with the sanity_check tool, use individual diagnostic tools like find_implementation() and query_component() as alternatives

• Legacy Files: Use git clean -fd after a git reset --hard to ensure all untracked files are removed when reverting to a previous version

• Duplicate Files: During our cleanup process, you may encounter duplicate files with extensions like .old, .backup, .fixed - these will be addressed in an upcoming release

• find_related_files Tool Errors: This tool has a known issue that will be fixed in an upcoming release

• Timeout Errors: We've improved timeout handling in version 0.5.4 with a more reliable threading-based mechanism and longer timeouts for search and write operations. We've also extended the MCP protocol timeout from 30s to 120s to prevent server disconnections. If you're still experiencing timeouts, try running python install_for_claude_code.py to upgrade your projects to the latest version.

• Old .ai_reference Format: For projects with older format .ai_reference directories, run the installer with python install_for_claude_code.py which will automatically detect and offer to upgrade these directories

• Tool Timeout Performance Issues: If tools are taking too long and timing out, use the hierarchical tool selection approach described in the "Optimized Tool Usage" section above. Always query the component registry and script index before doing direct filesystem operations.

Additional documentation is available in the docs directory:

• AI Librarian Guide
• Task System Documentation
• MCP Server Template
• Project Structure
• Tools Reference
• Upgrading AI Reference
• Upgrade Manager
• Think Tool Guide

Upcoming Releases

• Beta Release: Advanced GUI interface improvements coming soon
• Codebase Cleanup: Consolidation of duplicate files and legacy code
• Sanity Check Improvements: Enhanced diagnostic capabilities and reporting
• GUI Improvements: Enhanced configurator interface with cleanup utilities
• Project Templates: Starter templates for common project types

Recent Releases

• [0.5.8] Improved GUI (Current): Enhanced modern interface with Color Mode selection, font customization, and text size adjustments. Added dedicated Help & Troubleshooting tab, Developer tab with terminal functionality, on-demand log explorer with filtering, and removed server status monitoring to prevent Claude Desktop interference.
• [0.5.7] GUI Enhancements: Added Claude Desktop process management with restart capability, log filtering system, and improved Dashboard organization with more intuitive button layout
• [0.5.6] Upgrade Manager: Added project analysis and upgrade system with GUI integration, clear request queue functionality, and Think Tool reclassification
• [0.5.5] Git Integration: Added Git repository tracking and analysis capabilities, with new MCP tools to retrieve git information and generate history files for Claude

Future Plans

• IDE Integration: Extensions for VS Code and other IDEs
• Advanced Code Analysis: Deeper semantic code understanding
• Team Workflow Tools: Project management integration

Current Work in Progress

• Tool Index Improvements: Recently implemented the Simple Tool Index system with dramatic performance improvements:

  • Single-pass architecture replaces complex multi-phase processing
  • Direct function discovery with no subprocess handling
  • Up to 10x faster execution (< 5 seconds vs 60+ seconds previously)
  • Improved reliability with fewer failure points
  • Simplified output format for better maintainability

• Sanity Check & Security Analysis: The sanity_check tool has been significantly improved:

  • Integration with the Security Analyzer for comprehensive assessment
  • Support for severity levels (critical, warning, info)
  • Enhanced error handling and encoding fixes
  • Professional security assessment with CWE IDs
  • AST-based analysis for deeper code understanding
  • Improved reporting with structured outputs

• Directory Structure Cleanup: Ongoing consolidation of overlapping functionality:

  • Consolidating duplicate files in the librarian directory:
    • Merging enhanced file editing functionality
    • Standardizing naming conventions across modules
    • Removing deprecated functionality (basic indexer has been replaced by enhanced_indexer)
  • Cleaning up the gui directory:
    • Standardizing on configurator_new.py as the primary GUI implementation
    • Eliminating legacy and backup files
    • Adding a GUI button for legacy file pruning

• Filesystem Operations: Enhanced file editing and manipulation capabilities

• Robustness Improvements: Enhanced timeout and retry handling:

  • Automatic retry mechanisms for long-running operations
  • Improved queue management to prevent request collisions
  • Performance metrics for identifying bottlenecks
  • Smarter timeout handling with configurable thresholds