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
これにより、コーディネーターノードと、異なる性格特性を持つ2つのエージェントノードが起動します。その後、以下のサイトにアクセスしてください。
コンポーネントを個別に実行する
コンポーネントを個別に実行することもできます。
# 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 ファイルを参照してください。
謝辞