KOI-MCP 集成

Python 3.12 快速API 锦鲤网

将知识组织基础设施 (KOI) 与模型上下文协议 (MCP) 相集成的桥接框架，使自主代理能够交换丰富的个性特征并将能力作为标准化工具公开。

快速入门

先决条件

Python 3.12+
rid-lib （≥3.2.5）
锦鲤网(≥1.0.0b12)

安装

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

运行演示

查看 KOI-MCP 运行情况的最快方法是运行演示：

python scripts/demo.py

这提供了一个丰富的交互式控制台，其中包含详细的事件记录和组件状态显示。

或者，您可以使用主模块运行简化的演示：

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

这将启动一个协调器节点和两个具有不同特性的代理节点。然后您可以访问：

协调器注册表： http://localhost:9000/resources/list
有用的代理工具： http://localhost:8101/tools/list
创意代理工具： http://localhost:8102/tools/list

单独运行组件

您还可以单独运行组件：

# 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

建筑学

KOI-MCP 集成遵循协调器-适配器模式：

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 协调器节点：充当 KOI 网络的中心枢纽，处理代理发现和状态同步
MCP 适配器：将 KOI 个性包转换为与 MCP 兼容的资源和工具
代理节点：具有个性的个体代理，向网络广播其特征
MCP 注册服务器：将适配器的注册表公开为 MCP 兼容端点
MCP 代理服务器：每个代理的单独服务器，将其特定特征作为端点公开

代理个性模型

代理通过基于特征的个性模型来表达其能力：

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

每个特征可以是：

简单值（字符串、数字、布尔值、列表）
具有元数据（描述、类型、is_callable）的复杂对象
可由 LLM 客户端调用的工具

实现细节

特工个性RID

该系统通过专用的AgentPersonality类型扩展了 KOI 的资源标识符 (RID) 系统：

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

人格概况图式

代理个性采用 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)

知识处理管道

该系统通过专门的处理程序与 KOI 的知识处理管道集成：

@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 端点集成

该集成提供了与 MCP 兼容的 REST 端点：

协调器注册表端点

GET /resources/list ：列出所有已知的代理资源
GET /resources/read/{resource_id} ：获取特定代理的详细信息
GET /tools/list ：列出所有可用的代理工具

代理服务器端点

GET /resources/list ：将此代理的个性列为资源
GET /resources/read/agent:{name} ：获取此代理的个性详细信息
GET /tools/list ：列出此代理的可调用特征作为工具
POST /tools/call/{trait_name} ：将特定特征作为工具调用

配置

协调器配置

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

代理配置

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

高级用法

运行时更新特征

代理可以动态更新其特征：

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

自定义知识处理程序

您可以注册自定义处理程序以进行个性化处理：

@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

发展

运行测试

# Run all tests
pytest

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

项目结构

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

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

基于KOI-Net库构建，用于分布式知识组织
与新兴的模型上下文协议 (MCP)标准兼容，用于 LLM 工具集成

KOI-MCP Integration