KOI-MCP 통합
지식 조직 인프라(KOI)와 모델 컨텍스트 프로토콜(MCP)을 통합하는 브리징 프레임워크로, 자율 에이전트가 풍부한 성격 특성을 교환하고 표준화된 도구로 기능을 공개할 수 있도록 합니다.
빠른 시작
필수 조건
설치
지엑스피1
데모 실행
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.jsonRelated 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| CKOI 코디네이터 노드 : 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
}
}
}
}각 특성은 다음과 같습니다.
간단한 값(문자열, 숫자, 부울, 목록)
메타데이터(설명, 유형, 호출 가능 여부)가 있는 복잡한 객체
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_CHAINMCP 엔드포인트 통합
통합은 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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
감사의 말
분산 지식 구성을 위한 KOI-Net 라이브러리 기반 구축
LLM 도구 통합을 위한 새로운 모델 컨텍스트 프로토콜(MCP) 표준과 호환