Which integrations are available for this server?

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. Used for data validation and settings management, structuring agent personalities and ensuring compatibility with the MCP schema format. Testing framework used for validating the KOI-MCP integration functionality. Provides the runtime environment for the KOI-MCP integration, enabling implementation of the bridging framework between Knowledge Organization Infrastructure and Model Context Protocol. Provides status badges for displaying Python version, FastAPI version, and KOI-Net version information.

How do I use KOI-MCP Integration?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@KOI-MCP Integration list available agents and their personality traits" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

KOI-MCP Integration

Python 3.12 FastAPI KOI-Net

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

Python 3.12+
rid-lib (≥3.2.5)
koi-net (≥1.0.0b12)

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:

Coordinator Registry: http://localhost:9000/resources/list
Helpful Agent Tools: http://localhost:8101/tools/list
Creative Agent Tools: http://localhost:8102/tools/list

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

Related MCP server: MemoDB MCP Server

Architecture

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

flowchart TD
    subgraph "Coordinator-Adapter Node"
        CN[KOI Coordinator Node]
        AD[MCP Adapter]
        MC[MCP Context Registry]
    end

    subgraph "Agent Node A"
        A1[KOI Agent Node]
        A2[Personality Bundle]
        A3[MCP Server]
    end

    subgraph "Agent Node B"
        B1[KOI Agent Node]
        B2[Personality Bundle]
        B3[MCP Server]
    end

    CN <-->|Node Discovery| A1
    CN <-->|Node Discovery| B1
    A1 -->|Personality Broadcast| CN
    B1 -->|Personality Broadcast| CN
    CN --> AD
    AD --> MC
    MC -->|Agent Registry| C[LLM Clients]
    A3 -->|Tools/Resources| C
    B3 -->|Tools/Resources| C

KOI Coordinator Node: Acts as a central hub for the KOI network, handling agent discovery and state synchronization
MCP Adapter: Converts KOI personality bundles into MCP-compatible resources and tools
Agent Nodes: Individual agents with personalities that broadcast their traits to the network
MCP Registry Server: Exposes the adapter's registry as MCP-compatible endpoints
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

Built on the KOI-Net library for distributed knowledge organization
Compatible with the emerging Model Context Protocol (MCP) standard for LLM tool integration

KOI-MCP Integration

KOI-MCP Integration

Quick Start

Prerequisites

Installation

Running the Demo

Running Components Individually

Architecture

Agent Personality Model

Implementation Details

Agent Personality RID

Personality Profile Schema

Knowledge Processing Pipeline

MCP Endpoint Integration

Coordinator Registry Endpoints

Agent Server Endpoints

Configuration

Coordinator Configuration

Agent Configuration

Advanced Usage

Updating Traits at Runtime

Custom Knowledge Handlers

Development

Running Tests

Project Structure

License

Acknowledgments

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API