Skip to content

mcp-integration.md

Latest commit

 

History

History
299 lines (213 loc) · 8.08 KB

mcp-integration.md

File metadata and controls

299 lines (213 loc) · 8.08 KB
description Connect Empathy Framework to Claude Code via MCP. Enable AI workflows, agent coordination, and pattern learning in your IDE.

MCP Integration (v5.1.1+)

Connect Empathy Framework workflows directly to Claude Code or Claude Desktop using the Model Context Protocol.

New in v5.1.1: Empathy MCP server exposes all production workflows as native tools - security audits, test generation, performance analysis, and more.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI applications to external tools and data sources. Empathy Framework exposes its workflows, authentication system, and telemetry as MCP tools.

Quick Setup

Option 1: Claude Code (Automatic)

Best for: Development workflows in VSCode

Empathy Framework includes .claude/mcp.json configuration. Claude Code automatically discovers the MCP server when you open the project.

  1. Install Empathy Framework:
pip install empathy-framework[developer]
  1. Open project in Claude Code

The MCP server is automatically configured via .claude/mcp.json:

{
  "mcpServers": {
    "empathy": {
      "command": "python",
      "args": ["-m", "empathy_os.mcp.server"],
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

  1. Restart Claude Code to load the server

  2. Use natural language:

"Run a security audit on src/"
"Generate tests for config.py"
"Check my authentication configuration"
"Analyze performance bottlenecks"

Option 2: Claude Desktop (Manual)

Best for: General-purpose AI workflows

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "empathy": {
            "command": "python",
            "args": ["-m", "empathy_os.mcp.server"],
            "env": {
                "ANTHROPIC_API_KEY": "your-api-key-here",
                "PYTHONPATH": "/path/to/empathy-framework/src"
            }
        }
    }
}

Then restart Claude Desktop.

Available Tools (10)

The Empathy MCP server exposes all production workflows as tools:

Workflow Tools

Tool Description Required Args
security_audit Scan code for vulnerabilities, dangerous patterns, security issues path
bug_predict Analyze code patterns and predict potential bugs path
code_review Comprehensive code quality analysis with suggestions path
test_generation Generate tests for code (supports batch mode) module, batch (optional)
performance_audit Identify bottlenecks, memory leaks, optimization opportunities path
release_prep Run release checks: health, security, changelog path (optional)

Authentication & Monitoring Tools

Tool Description Required Args
auth_status Get authentication strategy status and configuration none
auth_recommend Get authentication recommendation for a file file_path
telemetry_stats Get cost savings, cache hit rates, workflow performance days (optional)
dashboard_status Get agent coordination dashboard status none

MCP Resources (3)

Resource URI Description
empathy://workflows List of all available workflows
empathy://auth/config Current authentication strategy configuration
empathy://telemetry Cost tracking and performance metrics

Example Usage

In Claude Code

Natural language commands are automatically routed to the appropriate tool:

Security Analysis:

User: "Run a security audit on the authentication module"
Claude: [Invokes security_audit tool with path="src/auth/"]

Test Generation:

User: "Generate tests for the config module"
Claude: [Invokes test_generation tool with module="src/empathy_os/config.py"]

Cost Optimization:

User: "What's my current authentication setup?"
Claude: [Invokes auth_status tool]
Response: {
  "success": true,
  "subscription_tier": "max",
  "default_mode": "api",
  "setup_completed": true
}

In Claude Desktop

Direct tool invocation or natural language:

You: Check for security vulnerabilities in my API code

Claude: I'll run a security audit using the empathy security_audit tool.

[Invokes security_audit(path="src/api/")]

Found 3 medium-severity issues:

  1. SQL injection risk in query builder (line 42)
  2. Missing input validation on user endpoint (line 78)
  3. Weak password hashing algorithm (line 156)

Testing the MCP Server

Quick Test

# Test tool listing
echo '{"method":"tools/list","params":{}}' | PYTHONPATH=./src python -m empathy_os.mcp.server

# Test tool execution
echo '{"method":"tools/call","params":{"name":"auth_status","arguments":{}}}' | PYTHONPATH=./src python -m empathy_os.mcp.server

Verify Integration

# Check server starts without errors
python -m empathy_os.mcp.server --help

# View comprehensive test results
cat .claude/MCP_TEST_RESULTS.md

Verification Hooks (v5.1.1+)

Empathy automatically validates outputs via Claude Code hooks:

Python File Validation:

  • Syntax checking after file writes
  • Imports and dependencies verified

JSON File Validation:

  • Format checking after file writes
  • Schema validation where applicable

Workflow Output Verification:

  • AI-powered validation of workflow results
  • Ensures required fields are present
  • Catches common errors

Configuration in .claude/settings.local.json (automatically set up).

Troubleshooting

Server Not Starting

Check Python environment:

python -c "import empathy_os.mcp.server; print('OK')"

Check PYTHONPATH:

# Should include src directory
echo $PYTHONPATH

Tools Not Available in Claude Code

  1. Verify .claude/mcp.json exists in project root
  2. Restart Claude Code completely
  3. Check Claude Code status bar for "empathy" server
  4. Review logs in Claude Code output panel

Tools Not Available in Claude Desktop

  1. Verify config path is correct for your OS
  2. Check JSON syntax - use a validator
  3. Set PYTHONPATH to absolute path of empathy-framework/src
  4. Restart Claude Desktop fully (quit and reopen)

Tool Execution Fails

Check API key:

echo $ANTHROPIC_API_KEY

Check workflow dependencies:

pip install empathy-framework[developer]

Review error logs:

  • Claude Code: Output panel → "Claude Code" channel
  • Claude Desktop: Application logs
  • Direct test: Stderr output from python command

MCP vs CLI vs Python API

Use Case Best Interface
Development in VSCode MCP (Claude Code) - Natural language, automatic discovery
Interactive exploration MCP (Claude Desktop) - Conversational, guided workflows
CI/CD pipelines CLI - empathy workflow run security-audit
Custom integrations Python API - Full programmatic control

Alternative Clients

The MCP server works with any MCP-compatible client:

  • Claude Code (VSCode extension) - Automatic project discovery
  • Claude Desktop - General-purpose AI assistant
  • Cursor IDE - Similar configuration to Claude Desktop
  • Custom clients - Use the MCP SDK to connect
  • CLI testing - Pipe JSON-RPC messages directly

Next Steps

Legacy: Socratic MCP Server

Note: The Socratic workflow builder MCP server (empathy_os.socratic.mcp_server) is deprecated in v5.1.1+. Use the production Empathy MCP server (empathy_os.mcp.server) instead, which exposes all workflows directly.