Koi-Mcp桥梁框架

@BlockScience/koi-mcp
0 Stars 156 次浏览 BlockScience 更新于 2026-08-23

一个桥梁框架，将知识组织基础设施（KOI）与模型上下文协议（MCP）集成在一起，使自主代理能够交换个性特征，并将功能作为标准化工具进行展示。

知识管理与记忆开发者工具
该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

KOI-MCP 集成

Python 3.12
FastAPI
KOI-Net

这是一个将知识组织基础设施 (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 的实际效果，可以运行演示：

python scripts/demo.py

这提供了一个具有详细事件日志和组件状态显示的丰富交互式控制台。

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

# 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 集成遵循 协调器-适配器模式：

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

每个特征可以是：

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

实现细节

代理个性 RID

系统扩展了 KOI 的资源标识符 (RID) 系统，增加了专用的 AgentPersonality 类型：

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 文件。

致谢

查看源码 项目主页

相关 MCP 服务

Markmap思维导图
jinzcdev/Markmap
Markmap MCP 服务器基于模型上下文协议（MCP），允许一键将 Markdown 文本转换为交互式思维导图，支持多种格式导出和丰富的交互操作。它基于开源项目 markmap 构建。
LeetCode(力扣)
jinzcdev/leetcode-mcp-server
MCP 服务器实现 LeetCode API 集成，支持自动化获取编程题库、用户数据和竞赛信息。
Github的维基百科DeepWiKi
@regenrek/mcp-deepwiki
📖 MCP 服务器用于获取 deepwiki.com 的最新知识，并在 Cursor 和其他代码编辑器中使用
微信读书
@package/mcp-server-weread
一个为微信读书提供MCP（Model Context Protocol）服务的工具，支持将微信读书的书籍、笔记和划线数据提供给支持MCP的大语言模型客户端，如Claude Desktop。