kollabor 0.4.9__py3-none-any.whl → 0.4.15__py3-none-any.whl

agents/kollabor/debug-mcp-integration.md

@@ -0,0 +1,521 @@
+<!-- MCP Integration Troubleshooting skill - diagnose and fix MCP server connections -->
+
+skill name: debug-mcp-integration
+
+purpose:
+  diagnose mcp (model context protocol) server connection issues,
+  verify tool availability, and debug tool execution failures.
+  mcp enables external tools and services to integrate with the llm.
+
+when to use:
+  - mcp tools not appearing in available tools list
+  - mcp server fails to start or connect
+  - tool execution returns errors
+  - server responds but tools are not registered
+  - need to verify mcp configuration is correct
+
+
+methodology:
+
+  phase 1: verify mcp configuration
+  phase 2: test server connectivity
+  phase 3: inspect tool registration
+  phase 4: debug tool execution
+  phase 5: analyze logs and errors
+
+
+phase 1: verify mcp configuration
+
+
+check mcp settings file locations
+
+mcp configuration is loaded from two locations (local overrides global):
+
+  [1] global: ~/.kollabor-cli/mcp/mcp_settings.json
+  [2] local:  .kollabor-cli/mcp/mcp_settings.json  (takes priority)
+
+verify local config exists:
+  <read><file>.kollabor-cli/mcp/mcp_settings.json</file></read>
+
+verify global config exists:
+  <terminal>cat ~/.kollabor-cli/mcp/mcp_settings.json</terminal>
+
+list mcp directory contents:
+  <terminal>find .kollabor-cli/mcp -type f 2>/dev/null</terminal>
+  <terminal>find ~/.kollabor-cli/mcp -type f 2>/dev/null</terminal>
+
+
+understand mcp settings structure
+
+valid mcp_settings.json format:
+  {
+    "servers": {
+      "server-name": {
+        "type": "stdio",
+        "command": "server-executable --arg1 --arg2",
+        "enabled": true
+      }
+    }
+  }
+
+required fields:
+  - type: must be "stdio" (http not yet implemented)
+  - command: full command to start the server
+  - enabled: true/false (optional, defaults to true)
+
+common configuration errors:
+  [error] missing "type" field
+  [error] command path not executable
+  [error] command requires absolute path
+  [error] enabled: false (server disabled)
+  [error] malformed json
+
+
+validate configuration syntax
+
+check json validity:
+  <terminal>python -c "import json; json.load(open('.kollabor-cli/mcp/mcp_settings.json'))"</terminal>
+
+check for syntax errors:
+  <terminal>python -m json.tool .kollabor-cli/mcp/mcp_settings.json</terminal>
+
+verify each server entry:
+  <terminal>grep -A 5 '"servers"' .kollabor-cli/mcp/mcp_settings.json</terminal>
+
+
+verify server commands are executable
+
+for each server in config, test if command exists:
+  <terminal>which <server-executable></terminal>
+
+example for npx-based servers:
+  <terminal>which npx</terminal>
+  <terminal>npx --version</terminal>
+
+example for python-based servers:
+  <terminal>which python</terminal>
+  <terminal>python -c "import <server-module>"</terminal>
+
+
+phase 2: test server connectivity
+
+
+manual server connection test
+
+test starting the server manually:
+  <terminal><server-command-from-config></terminal>
+
+if server starts:
+  - check for initialization message
+  - look for protocol version in output
+  - verify it responds to json-rpc
+
+if server fails to start:
+  - check command syntax
+  - verify dependencies installed
+  - check for missing environment variables
+
+
+test mcp handshake using python
+
+create test script to verify mcp protocol:
+  <terminal>python -c "
+import asyncio
+import json
+import sys
+
+async def test_mcp():
+    cmd = '<server-command-from-config>'
+    proc = await asyncio.create_subprocess_exec(
+        *cmd.split(),
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE
+    )
+
+    # send initialize request
+    init_req = {
+        'jsonrpc': '2.0',
+        'id': '1',
+        'method': 'initialize',
+        'params': {
+            'protocolVersion': '2024-11-05',
+            'capabilities': {},
+            'clientInfo': {'name': 'test', 'version': '1.0'}
+        }
+    }
+
+    proc.stdin.write(json.dumps(init_req).encode() + b'\n')
+    await proc.stdin.drain()
+
+    # read response
+    response = await asyncio.wait_for(proc.stdout.readline(), timeout=5)
+    print(response.decode())
+
+    proc.terminate()
+    await proc.wait()
+
+asyncio.run(test_mcp())
+  "</terminal>
+
+
+verify server responses
+
+expected initialize response:
+  {
+    "jsonrpc": "2.0",
+    "id": "1",
+    "result": {
+      "protocolVersion": "2024-11-05",
+      "capabilities": {...},
+      "serverInfo": {...}
+    }
+  }
+
+error responses indicate:
+  - protocol mismatch
+  - server not mcp-compliant
+  - invalid client info
+
+
+phase 3: inspect tool registration
+
+
+check loaded mcp integration
+
+read the integration code:
+  <read><file>core/llm/mcp_integration.py</file><lines>1-100</lines></read>
+
+check initialization logs:
+  <terminal>grep -i "mcp" .kollabor-cli/logs/kollabor.log | tail -20</terminal>
+
+verify servers loaded:
+  <terminal>grep "Loaded.*MCP server" .kollabor-cli/logs/kollabor.log</terminal>
+
+verify tools registered:
+  <terminal>grep "Registered MCP tool" .kollabor-cli/logs/kollabor.log</terminal>
+
+
+check tool registry state
+
+the tool_registry stores discovered tools:
+  - key: tool name
+  - value: {server, definition, enabled}
+
+view registered tools in logs:
+  <terminal>grep "tools from.*server" .kollabor-cli/logs/kollabor.log</terminal>
+
+check tool count:
+  <terminal>grep "Got.*tools from" .kollabor-cli/logs/kollabor.log</terminal>
+
+
+test tool discovery
+
+trigger tool discovery manually:
+  <terminal>python -c "
+import asyncio
+from core.llm.mcp_integration import MCPIntegration
+
+async def test():
+    mcp = MCPIntegration()
+    print(f'Configured servers: {list(mcp.mcp_servers.keys())}')
+    discovered = await mcp.discover_mcp_servers()
+    print(f'Discovered: {json.dumps(discovered, indent=2)}')
+    print(f'Tool registry: {list(mcp.tool_registry.keys())}')
+    await mcp.shutdown()
+
+asyncio.run(test())
+  "</terminal>
+
+
+phase 4: debug tool execution
+
+
+check tool executor
+
+read tool executor code:
+  <read><file>core/llm/tool_executor.py</file><lines>312-374</lines></read>
+
+key execution flow:
+  1. llm requests tool call
+  2. tool_executor routes to _execute_mcp_tool
+  3. mcp_integration.call_mcp_tool invoked
+  4. connection.check -> tool call on server
+  5. result formatted and returned
+
+
+verify mcp tool call flow
+
+check mcp call_mcp_tool:
+  <read><file>core/llm/mcp_integration.py</file><lines>436-477</lines></read>
+
+verify connection is active:
+  <terminal>grep "server_connections" .kollabor-cli/logs/kollabor.log</terminal>
+
+check for reconnection attempts:
+  <terminal>grep "reconnect\|No active connection" .kollabor-cli/logs/kollabor.log</terminal>
+
+
+test individual tool call
+
+test a specific tool manually:
+  <terminal>python -c "
+import asyncio
+import json
+from core.llm.mcp_integration import MCPIntegration
+
+async def test_tool():
+    mcp = MCPIntegration()
+    await mcp.discover_mcp_servers()
+
+    tool_name = '<tool-name-to-test>'
+    arguments = {}  # add required args
+
+    result = await mcp.call_mcp_tool(tool_name, arguments)
+    print(f'Result: {json.dumps(result, indent=2)}')
+
+    await mcp.shutdown()
+
+asyncio.run(test_tool())
+  "</terminal>
+
+
+phase 5: analyze logs and errors
+
+
+common mcp error patterns
+
+error: "failed to start mcp server"
+  causes:
+    - command not found
+    - missing dependencies
+    - permission denied
+    - invalid command syntax
+
+  debug:
+    <terminal>which <executable-from-command></terminal>
+    <terminal><command> --help</terminal>
+    <terminal>ls -la $(which <executable>)</terminal>
+
+
+error: "initialization failed"
+  causes:
+    - server not mcp-compliant
+    - protocol version mismatch
+    - server crashed on startup
+    - timeout waiting for response
+
+  debug:
+    <terminal>grep "initialize.*failed" .kollabor-cli/logs/kollabor.log</terminal>
+    <terminal>grep -A 5 -B 5 "server.*initialized" .kollabor-cli/logs/kollabor.log</terminal>
+
+
+error: "tool not found"
+  causes:
+    - tool name mismatch
+    - server not connected
+    - tool not registered
+    - server disabled
+
+  debug:
+    <terminal>grep "tool_registry" .kollabor-cli/logs/kollabor.log</terminal>
+    <terminal>python -c "from core.llm.mcp_integration import MCPIntegration; import asyncio; asyncio.run(MCPIntegration().discover_mcp_servers())"</terminal>
+
+
+error: "server not initialized"
+  causes:
+    - handshake not completed
+    - connection dropped
+    - server crashed after start
+
+  debug:
+    <terminal>grep "initialized.*True" .kollabor-cli/logs/kollabor.log</terminal>
+    <terminal>grep "notifications/initialized" .kollabor-cli/logs/kollabor.log</terminal>
+
+
+error: "timeout waiting for response"
+  causes:
+    - server slow to respond
+    - tool execution taking too long
+    - server hung
+    - network issue (for http servers)
+
+  debug:
+    check default timeout in mcp_integration.py:413
+    verify server responds within timeout
+    check for resource constraints
+
+
+enable detailed mcp logging
+
+add debug logging to investigate:
+  <terminal>python -c "
+import logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger('core.llm.mcp_integration')
+logger.setLevel(logging.DEBUG)
+  "</terminal>
+
+run with debug output:
+  <terminal>python -c "
+import asyncio
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+from core.llm.mcp_integration import MCPIntegration
+
+async def test():
+    mcp = MCPIntegration()
+    await mcp.discover_mcp_servers()
+    await mcp.shutdown()
+
+asyncio.run(test())
+  "</terminal>
+
+
+troubleshooting checklist
+
+
+configuration
+  [ ] mcp_settings.json exists and valid json
+  [ ] at least one server configured
+  [ ] server commands use absolute paths or available in path
+  [ ] server type is "stdio"
+  [ ] enabled: true (or field omitted)
+
+
+server availability
+  [ ] server executable exists (which/where)
+  [ ] server dependencies installed
+  [ ] server runs when executed manually
+  [ ] server responds to initialize request
+  [ ] server sends notifications/initialized
+
+
+tool registration
+  [ ] discover_mcp_servers() completes
+  [ ] tools listed in discovered result
+  [ ] tools appear in tool_registry
+  [ ] tools marked as enabled: true
+
+
+execution
+  [ ] connection remains open after discovery
+  [ ] call_mcp_tool() reaches server
+  [ ] server responds within timeout
+  [ ] result formatted correctly
+
+
+logs
+  [ ] "mcp integration initialized" found
+  [ ] "started mcp server process" for each server
+  [ ] "mcp server.*initialized" for each server
+  [ ] "got n tools from" for each server
+  [ ] "registered mcp tool" for each tool
+
+
+example workflow
+
+
+scenario: filesystem tools not appearing
+
+step 1: check configuration
+  <read><file>.kollabor-cli/mcp/mcp_settings.json</file></read>
+
+step 2: verify server command
+  <terminal>which npx</terminal>
+  <terminal>npx -y @modelcontextprotocol/server-filesystem --help</terminal>
+
+step 3: check logs for loading
+  <terminal>grep "filesystem" .kollabor-cli/logs/kollabor.log</terminal>
+
+step 4: run manual discovery
+  <terminal>python -c "
+import asyncio
+from core.llm.mcp_integration import MCPIntegration
+
+async def test():
+    mcp = MCPIntegration()
+    print('servers:', list(mcp.mcp_servers.keys()))
+    discovered = await mcp.discover_mcp_servers()
+    for name, info in discovered.items():
+        print(f'{name}: {info[\"tool_count\"]} tools')
+    await mcp.shutdown()
+
+asyncio.run(test())
+  "</terminal>
+
+step 5: test tool call
+  <terminal>python -c "
+import asyncio
+from core.llm.mcp_integration import MCPIntegration
+
+async def test():
+    mcp = MCPIntegration()
+    await mcp.discover_mcp_servers()
+    result = await mcp.call_mcp_tool('read_file', {'path': '/tmp/test'})
+    print(result)
+    await mcp.shutdown()
+
+asyncio.run(test())
+  "</terminal>
+
+
+common mcp servers
+
+filesystem server:
+  command: npx -y @modelcontextprotocol/server-filesystem /allowed/path
+  tools: read_file, write_file, list_directory, directory_tree
+
+git server:
+  command: npx -y @modelcontextprotocol/server-git --repository /path/to/repo
+  tools: clone, commit, log, status, diff
+
+github server:
+  command: mcp-server-github
+  tools: create_issue, create_pull_request, get_file
+
+sqlite server:
+  command: mcp-server-sqlite --db-path /path/to/database.db
+  tools: query, execute, schema
+
+brave search server:
+  command: mcp-server-brave-search
+  tools: brave_search
+
+
+expected output
+
+when mcp integration is working correctly:
+  [ok] mcp integration initialized
+  [ok] loaded n mcp server configurations
+  [ok] started mcp server process: <server-name>
+  [ok] mcp server <server-name> initialized
+  [ok] got n tools from <server-name>
+  [ok] registered mcp tool: <tool-name> from <server-name>
+  [ok] executed mcp tool: <tool-name>
+
+
+when issues exist:
+  [error] failed to load mcp config
+  [warn] failed to start mcp server <name>
+  [warn] mcp server <name> initialization failed
+  [warn] got 0 tools from <name>
+  [error] tool '<name>' not found
+  [error] no active connection to server '<name>'
+
+
+final notes
+
+mcp integration requires:
+  - valid json-rpc 2.0 protocol implementation
+  - stdio communication with newline-delimited messages
+  - initialize handshake before tool operations
+  - server must respond within 30 seconds
+
+remember:
+  - local config overrides global config
+  - disabled servers are skipped
+  - connections must stay open for tool calls
+  - tools must be registered before use
+  - check logs for detailed error traces