KOI-MCP Integration

Integrations

  • Used as the web framework for implementing MCP-compatible REST endpoints, exposing agent personality traits and callable tools through standardized HTTP interfaces.

  • Referenced for hosting related components like rid-lib and koi-net dependencies.

  • Implements architecture diagrams in the documentation to visualize the Coordinator-Adapter pattern and component relationships.

KOI-MCP Integration

A bridging framework that integrates the Knowledge Organization Infrastructure (KOI) with the Model Context Protocol (MCP), enabling autonomous agents to exchange rich personality traits and expose capabilities as standardized tools.

Quick Start

Prerequisites

Installation

# Clone the repository git clone https://github.com/block-science/koi-mcp.git cd koi-mcp # Create and activate virtual environment uv venv --python 3.12 source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install the package with development dependencies uv pip install -e ".[dev]"

Running the Demo

The quickest way to see KOI-MCP in action is to run the demo:

python scripts/demo.py

This provides a rich interactive console with detailed event logging and component status displays.

Alternatively, you can run a simplified demo using the main module:

# Run demo (starts coordinator and two example agents) python -m koi_mcp.main demo

This starts a coordinator node and two agent nodes with different personality traits. You can then visit:

Running Components Individually

You can also run the components separately:

# Run coordinator node python -m koi_mcp.main coordinator # Run agent nodes python -m koi_mcp.main agent --config configs/agent1.json python -m koi_mcp.main agent --config configs/agent2.json

Architecture

The KOI-MCP integration follows a Coordinator-Adapter pattern:

  1. KOI Coordinator Node: Acts as a central hub for the KOI network, handling agent discovery and state synchronization
  2. MCP Adapter: Converts KOI personality bundles into MCP-compatible resources and tools
  3. Agent Nodes: Individual agents with personalities that broadcast their traits to the network
  4. MCP Registry Server: Exposes the adapter's registry as MCP-compatible endpoints
  5. MCP Agent Servers: Individual servers for each agent that expose their specific traits as endpoints

Agent Personality Model

Agents express their capabilities through a trait-based personality model:

# Example agent configuration { "agent": { "name": "helpful-agent", "version": "1.0", "traits": { "mood": "helpful", "style": "concise", "interests": ["ai", "knowledge-graphs"], "calculate": { "description": "Performs simple calculations", "is_callable": true } } } }

Each trait can be:

  • A simple value (string, number, boolean, list)
  • A complex object with metadata (description, type, is_callable)
  • A callable tool that can be invoked by LLM clients

Implementation Details

Agent Personality RID

The system extends KOI's Resource Identifier (RID) system with a dedicated AgentPersonality type:

class AgentPersonality(ORN): namespace = "agent.personality" def __init__(self, name, version): self.name = name self.version = version @property def reference(self): return f"{self.name}/{self.version}"

Personality Profile Schema

Agent personalities are structured using Pydantic models:

class PersonalityProfile(BaseModel): rid: AgentPersonality node_rid: KoiNetNode base_url: Optional[str] = None mcp_url: Optional[str] = None traits: List[PersonalityTrait] = Field(default_factory=list)

Knowledge Processing Pipeline

The system integrates with KOI's knowledge processing pipeline through specialized handlers:

@processor.register_handler(HandlerType.Bundle, rid_types=[AgentPersonality]) def personality_bundle_handler(proc: ProcessorInterface, kobj: KnowledgeObject): """Process agent personality bundles.""" try: # Validate contents as PersonalityProfile profile = PersonalityProfile.model_validate(kobj.contents) # Register with MCP adapter if available if mcp_adapter is not None: mcp_adapter.register_agent(profile) return kobj except ValidationError: return STOP_CHAIN

MCP Endpoint Integration

The integration provides MCP-compatible REST endpoints:

Coordinator Registry Endpoints

  • GET /resources/list: List all known agent resources
  • GET /resources/read/{resource_id}: Get details for a specific agent
  • GET /tools/list: List all available agent tools

Agent Server Endpoints

  • GET /resources/list: List this agent's personality as a resource
  • GET /resources/read/agent:{name}: Get this agent's personality details
  • GET /tools/list: List this agent's callable traits as tools
  • POST /tools/call/{trait_name}: Call a specific trait as a tool

Configuration

Coordinator Configuration

{ "coordinator": { "name": "koi-mcp-coordinator", "base_url": "http://localhost:9000/koi-net", "mcp_registry_port": 9000 } }

Agent Configuration

{ "agent": { "name": "helpful-agent", "version": "1.0", "base_url": "http://localhost:8100/koi-net", "mcp_port": 8101, "traits": { "mood": "helpful", "style": "concise", "interests": ["ai", "knowledge-graphs"], "calculate": { "description": "Performs simple calculations", "is_callable": true } } }, "network": { "first_contact": "http://localhost:9000/koi-net" } }

Advanced Usage

Updating Traits at Runtime

Agents can update their traits dynamically:

agent = KoiAgentNode(...) agent.update_traits({ "mood": "enthusiastic", "new_capability": { "description": "A new capability added at runtime", "is_callable": True } })

Custom Knowledge Handlers

You can register custom handlers for personality processing:

@processor.register_handler(HandlerType.Network, rid_types=[AgentPersonality]) def my_custom_network_handler(proc: ProcessorInterface, kobj: KnowledgeObject): # Custom logic for determining which nodes should receive personality updates # ... return kobj

Development

Running Tests

# Run all tests pytest # Run tests with coverage report pytest --cov=koi_mcp

Project Structure

koi-mcp/ ├── configs/ # Configuration files for nodes ├── docs/ # Documentation and design specs ├── scripts/ # Utility scripts ├── src/ # Source code │ └── koi_mcp/ │ ├── koi/ # KOI integration components │ │ ├── handlers/ # Knowledge processing handlers │ │ └── node/ # Node implementations │ ├── personality/ # Personality models │ │ ├── models/ # Data models for traits and profiles │ │ └── rid.py # Agent personality RID definition │ ├── server/ # MCP server implementations │ │ ├── adapter/ # KOI-to-MCP adapter │ │ ├── agent/ # Agent server │ │ └── registry/ # Registry server │ ├── utils/ # Utility functions │ ├── config.py # Configuration handling │ └── main.py # Main entry point └── tests/ # Test suite

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

-
security - not tested
F
license - not found
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A bridging framework that integrates Knowledge Organization Infrastructure (KOI) with Model Context Protocol (MCP), enabling autonomous agents to exchange personality traits and expose capabilities as standardized tools.

  1. Quick Start
    1. Prerequisites
    2. Installation
    3. Running the Demo
    4. Running Components Individually
  2. Architecture
    1. Agent Personality Model
      1. Implementation Details
        1. Agent Personality RID
        2. Personality Profile Schema
        3. Knowledge Processing Pipeline
      2. MCP Endpoint Integration
        1. Coordinator Registry Endpoints
        2. Agent Server Endpoints
      3. Configuration
        1. Coordinator Configuration
        2. Agent Configuration
      4. Advanced Usage
        1. Updating Traits at Runtime
        2. Custom Knowledge Handlers
      5. Development
        1. Running Tests
      6. Project Structure
        1. License
          1. Acknowledgments

            Related MCP Servers

            • -
              security
              F
              license
              -
              quality
              Facilitates interaction and context sharing between AI models using the standardized Model Context Protocol (MCP) with features like interoperability, scalability, security, and flexibility across diverse AI systems.
              Last updated -
              1
              Python
            • -
              security
              F
              license
              -
              quality
              A comprehensive suite of Model Context Protocol servers designed to extend AI agent Claude's capabilities with integrations for knowledge management, reasoning, advanced search, news access, and workspace tools.
              Last updated -
              5
              TypeScript
              • Apple
            • A
              security
              F
              license
              A
              quality
              A Model Context Protocol server that enables AI models to interact with SourceSync.ai's knowledge management platform for managing documents, ingesting content from various sources, and performing semantic searches.
              Last updated -
              25
              14
              • Apple
              • Linux
            • -
              security
              F
              license
              -
              quality
              Manages AI conversation context and personal knowledge bases through the Model Context Protocol (MCP), providing tools for user data, conversation content, and knowledge management.
              Last updated -
              1
              TypeScript

            View all related MCP servers

            ID: uthob76e6x