Integración KOI-MCP

Python 3.12 API rápida KOI-Net

Un marco de conexión que integra la Infraestructura de Organización del Conocimiento (KOI) con el Protocolo de Contexto Modelo (MCP), permitiendo que los agentes autónomos intercambien rasgos de personalidad enriquecedores y expongan capacidades como herramientas estandarizadas.

Inicio rápido

Prerrequisitos

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

Instalación

# 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]"

Ejecución de la demostración

La forma más rápida de ver KOI-MCP en acción es ejecutar la demostración:

python scripts/demo.py

Esto proporciona una consola interactiva enriquecida con registro detallado de eventos y visualización del estado de los componentes.

Alternativamente, puede ejecutar una demostración simplificada utilizando el módulo principal:

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

Esto inicia un nodo coordinador y dos nodos agente con diferentes rasgos de personalidad. Luego, puedes visitar:

Registro del coordinador: http://localhost:9000/resources/list
Herramientas útiles del agente: http://localhost:8101/tools/list
Herramientas del agente creativo: http://localhost:8102/tools/list

Ejecución de componentes individualmente

También puedes ejecutar los componentes por separado:

# 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

Arquitectura

La integración KOI-MCP sigue un patrón Coordinador-Adaptador :

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

Nodo coordinador KOI : actúa como un centro central para la red KOI, manejando el descubrimiento de agentes y la sincronización de estados.
Adaptador MCP : convierte los paquetes de personalidad KOI en recursos y herramientas compatibles con MCP
Nodos de agente : agentes individuales con personalidades que transmiten sus rasgos a la red.
Servidor de registro MCP : expone el registro del adaptador como puntos finales compatibles con MCP
Servidores de agente MCP : servidores individuales para cada agente que exponen sus características específicas como puntos finales

Modelo de personalidad del agente

Los agentes expresan sus capacidades a través de un modelo de personalidad basado en rasgos:

# 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
      }
    }
  }
}

Cada rasgo puede ser:

Un valor simple (cadena, número, booleano, lista)
Un objeto complejo con metadatos (descripción, tipo, es invocable)
Una herramienta invocable que los clientes LLM pueden invocar

Detalles de implementación

Personalidad del agente RID

El sistema amplía el sistema de Identificador de recursos (RID) de KOI con un tipo AgentPersonality dedicado:

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}"

Esquema del perfil de personalidad

Las personalidades de los agentes se estructuran utilizando modelos Pydantic:

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)

Canal de procesamiento de conocimiento

El sistema se integra con el flujo de procesamiento de conocimiento de KOI a través de controladores especializados:

@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

Integración de puntos finales de MCP

La integración proporciona puntos finales REST compatibles con MCP:

Puntos finales del registro del coordinador

GET /resources/list : enumera todos los recursos del agente conocidos
GET /resources/read/{resource_id} : Obtener detalles de un agente específico
GET /tools/list : enumera todas las herramientas de agente disponibles

Puntos finales del servidor del agente

GET /resources/list : enumera la personalidad de este agente como un recurso
GET /resources/read/agent:{name} : Obtener los detalles de personalidad de este agente
GET /tools/list : enumera los rasgos invocables de este agente como herramientas
POST /tools/call/{trait_name} : Llamar a un rasgo específico como herramienta

Configuración

Configuración del coordinador

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

Configuración del agente

{
  "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"
  }
}

Uso avanzado

Actualización de rasgos en tiempo de ejecución

Los agentes pueden actualizar sus rasgos dinámicamente:

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

Manejadores de conocimiento personalizados

Puede registrar controladores personalizados para el procesamiento de personalidad:

@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

Desarrollo

Ejecución de pruebas

# Run all tests
pytest

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

Estructura del proyecto

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

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

Construido sobre la biblioteca KOI-Net para la organización del conocimiento distribuido
Compatible con el estándar emergente de Protocolo de Contexto de Modelo (MCP) para la integración de herramientas LLM

KOI-MCP Integration