KOI-MCP 集成
将知识组织基础设施 (KOI) 与模型上下文协议 (MCP) 相集成的桥接框架，使自主代理能够交换丰富的个性特征并将能力作为标准化工具公开。
快速入门
先决条件
安装
# 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 运行情况的最快方法是运行演示：
这提供了一个丰富的交互式控制台，其中包含详细的事件记录和组件状态显示。
或者，您可以使用主模块运行简化的演示：
# Run demo (starts coordinator and two example agents)
python -m koi_mcp.main demo
这将启动一个协调器节点和两个具有不同特性的代理节点。然后您可以访问：
单独运行组件
您还可以单独运行组件：
# 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
建筑学
KOI-MCP 集成遵循协调器-适配器模式：
- 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 文件。
致谢