@vacbo/smart-agents-mcp-client

MCP client proxy for Smart Agents context management system.

Bridges Cursor AI to your Smart Agents Context Manager via HTTPS using the official Model Context Protocol Streamable HTTP transport.

Features

✅ Streamable HTTP Transport - Full MCP specification compliance
✅ Session Management - Persistent sessions with automatic reconnection
✅ Automatic Session Recovery - Seamless recovery from server restarts and session expiration
✅ SSE Streaming - Real-time responses via Server-Sent Events
✅ Authentication - API key-based authentication
✅ Error Handling - Robust error recovery and retry logic with configurable limits

Installation

Using bunx (recommended)

No installation needed! Just configure in Cursor:

{
  "mcpServers": {
    "smart-agents-context": {
      "command": "bunx",
      "args": ["@vacbo/smart-agents-mcp-client"],
      "env": {
        "SMART_AGENTS_API_KEY": "your-key-here",
        "SMART_AGENTS_MCP_URL": "https://mcp.vacbo.dev"
      }
    }
  }
}

Using npx

{
  "mcpServers": {
    "smart-agents-context": {
      "command": "npx",
      "args": ["-y", "@vacbo/smart-agents-mcp-client"],
      "env": {
        "SMART_AGENTS_API_KEY": "your-key-here",
        "SMART_AGENTS_MCP_URL": "https://mcp.vacbo.dev"
      }
    }
  }
}

Global Installation

npm install -g @vacbo/smart-agents-mcp-client
# or
bun install -g @vacbo/smart-agents-mcp-client

Then configure in Cursor:

{
  "mcpServers": {
    "smart-agents-context": {
      "command": "smart-agents-mcp-client",
      "env": {
        "SMART_AGENTS_API_KEY": "your-key-here",
        "SMART_AGENTS_MCP_URL": "https://mcp.vacbo.dev"
      }
    }
  }
}

Configuration

Required Environment Variables

• SMART_AGENTS_API_KEY - Your API key for authentication
• SMART_AGENTS_MCP_URL - Server URL (e.g., https://mcp.vacbo.dev)

Optional Environment Variables

• DEBUG=1 - Enable debug logging to /tmp/mcp-client-debug.log

Available Tools

The client provides access to these MCP tools:

retrieve_context

Search hierarchical memory for relevant documentation and context.

Parameters:

• query (string, required) - Natural language search query
• max_results (number, optional) - Maximum results to return (1-20, default: 5)
• min_relevance (number, optional) - Minimum relevance score (0.0-1.0, default: 0.7)

list_topics

List all available topics in the knowledge base with coverage scores.

Parameters:

• domain (string, optional) - Filter by domain (frontend, backend, database, etc.)
• min_coverage (number, optional) - Minimum coverage threshold (0.0-1.0, default: 0)

check_coverage

Check if documentation exists for specific topics (prevents hallucination).

Parameters:

• topics (string[], required) - List of topics to check

store_context

Store new documentation or context in the knowledge base.

Parameters:

• content (string, required) - The documentation content (minimum 50 characters)
• title (string, required) - Title of the documentation
• tags (string[], required) - Topics/tags for categorization
• domain (string, optional) - Domain category (default: "general")
• importance (number, optional) - Importance score (0.0-1.0, default: 0.5)

How It Works

This client implements the Streamable HTTP transport pattern from the MCP specification:

1. Initialize: POST /mcp with initialize method to establish session
2. Session: Server returns Mcp-Session-Id header for subsequent requests
3. Streaming: Optional GET /mcp SSE stream for async notifications
4. Requests: All requests via POST /mcp with session ID, responses in POST body as SSE
5. Cleanup: DELETE /mcp to terminate session

Architecture

┌─────────┐  stdio   ┌──────────┐  HTTPS/SSE  ┌──────────┐
│ Cursor  │ ◄─────► │  Client  │ ◄─────────► │  Server  │
│   IDE   │  JSON-   │  Proxy   │   Streamable│   MCP    │
└─────────┘  RPC     └──────────┘   HTTP      └──────────┘

The client:

• Reads JSON-RPC messages from stdin (from Cursor)
• Forwards them to the remote MCP server via HTTPS
• Parses SSE-formatted responses from POST bodies
• Writes JSON-RPC responses to stdout (back to Cursor)
• Maintains session state and handles reconnection

Session Recovery

The client automatically recovers from session expiration and server restarts:

How It Works

1. Detection: Client detects session expiration errors (HTTP 404, "Session not found")
2. Recovery: Automatically reinitializes the session with the server
3. Retry: Retries the failed request with the new session
4. Limits: Maximum 2 retry attempts per request to prevent infinite loops

Recovery Scenarios

✅ Server Restart: Client detects stale session and reinitializes
✅ Session Timeout: Automatic recovery after idle timeout
✅ Network Issues: Graceful handling with retry logic
✅ Multiple Requests: Prevents duplicate recovery attempts

Configuration

• Max Retry Attempts: 2 (hardcoded, prevents infinite loops)
• Session State: Automatically cleared on expiration
• Pending Requests: Stored for retry after recovery

Error Codes

The client detects these session expiration indicators:

• -32003 - MCP "Session not found" error code
• -32001 - Connection closed error code
• HTTP 404 - Session not found HTTP error
• Any error message containing "Session not found"

Debugging

Enable debug mode to see detailed logs:

DEBUG=1 smart-agents-mcp-client

Debug logs include:

• Session initialization and recovery events
• Retry attempts and success/failure
• Error detection and analysis
• Request/response flow

Logs are written to stderr for easy filtering.

Requirements

• Node.js >= 18.0.0
• Active internet connection
• Valid API key and server URL

License

MIT

Links

• Model Context Protocol Specification
• Streamable HTTP Transport
• Smart Agents System