k5tuck/binelek-mcp-server

Binelek MCP Server

Model Context Protocol (MCP) server for the Binelek Platform. This server provides MCP tools for interacting with the Binelek knowledge graph, search, AI, and data pipeline services through the API Gateway.

Features

• Knowledge Graph Tools: Query, create, update, and delete entities and relationships
• Search Tools: Semantic, keyword, and hybrid search capabilities
• AI Tools: Chat with AI, make predictions, analyze entities
• Pipeline Tools: Trigger and monitor data pipelines
• Admin Tools: Domain configuration, YAML validation, code generation

Installation

npm install
npm run build

Configuration

Create a .env file (copy from .env.example):

BINELEK_GATEWAY_URL=http://localhost:8092
BINELEK_TENANT_ID=core
BINELEK_JWT_TOKEN=your-jwt-token-here
LOG_LEVEL=info

Usage

As a Standalone Server

npm start

With Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "binelek": {
      "command": "node",
      "args": ["/path/to/binelek-mcp-server/build/index.js"],
      "env": {
        "BINELEK_GATEWAY_URL": "http://localhost:8092",
        "BINELEK_TENANT_ID": "core",
        "BINELEK_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}

With VS Code Extension

The binelek-vscode-extension uses this MCP server. See that project's README for setup instructions.

Available Tools

Ontology Tools

• binelek_get_entity - Get entity by ID
• binelek_query_entities - Execute Cypher queries
• binelek_create_entity - Create new entities
• binelek_update_entity - Update existing entities
• binelek_delete_entity - Delete entities
• binelek_get_relationships - Get entity relationships
• binelek_create_relationship - Create relationships

Search Tools

• binelek_semantic_search - Semantic search using embeddings
• binelek_keyword_search - Keyword search with Elasticsearch
• binelek_hybrid_search - Combined semantic + keyword search

AI Tools

• binelek_ai_chat - Chat with Binelek AI assistant
• binelek_ai_predict - Make predictions with ML models
• binelek_ai_analyze_entity - AI-powered entity analysis

Pipeline Tools

• binelek_list_pipelines - List all pipelines
• binelek_get_pipeline - Get pipeline details
• binelek_trigger_pipeline - Trigger pipeline execution
• binelek_get_pipeline_runs - Get pipeline run history

Admin Tools

• binelek_list_domains - List available domains
• binelek_get_domain - Get domain configuration
• binelek_get_ontology_schema - Get ontology YAML schema
• binelek_validate_yaml - Validate ontology YAML
• binelek_generate_code - Generate code from YAML

Authentication

The MCP server uses JWT tokens to authenticate with the Binelek API Gateway. You can:

1. Set in environment: BINELEK_JWT_TOKEN=your-token
2. Set in .env file: See .env.example
3. Pass via MCP config: When configuring in Claude Desktop or VS Code

To obtain a JWT token, authenticate through the Binelek platform or use the auth API:

curl -X POST http://localhost:8092/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your-password"}'

Architecture

MCP Client (Claude/VS Code)
  ↓ stdio
MCP Server (this project)
  ↓ HTTP/REST
API Gateway (localhost:8092)
  ↓ routes to
Backend Services (Ontology, Search, AI, Pipeline, etc.)

Important: The MCP server communicates ONLY with the API Gateway, never directly with backend services. This ensures proper authentication, tenant isolation, and rate limiting.

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode (auto-reload)
npm run dev

# Type check
npm run type-check

Error Handling

The server handles errors gracefully and returns them in MCP format:

{
  "content": [{
    "type": "text",
    "text": "Error: Entity not found: prop_123"
  }],
  "isError": true
}

License

MIT