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