Claude MCP Agent

Claude MCP Agent

一个灵活的模型上下文协议 (MCP) 客户端实现，设计用于与 AI Agent 协同工作，重点关注状态管理和服务配置。

概览

Claude MCP Agent 是一个 Python 库，使 AI Agent 能够使用结构化状态管理与 MCP 服务交互。该 Agent 接受任何 Pydantic 模型作为其状态，允许灵活定义上下文并将其转换为兼容 Claude 的提示词。这种方法能够精确控制 Agent 可用的上下文，同时保持类型安全性和验证。

示例状态定义

from pydantic import BaseModel
from typing import List, Optional

class ConversationContext(BaseModel):
    current_task: str
    relevant_facts: List[str]
    user_preferences: dict
    conversation_history: Optional[List[dict]] = []
    
# The agent will intelligently translate this structure 
# into context that Claude can understand
state = ConversationContext(
    current_task="Weather analysis for trip planning",
    relevant_facts=[
        "User is planning a trip to Seattle",
        "Trip dates: June 15-20",
        "Outdoor activities planned"
    ],
    user_preferences={
        "temperature_unit": "celsius",
        "activity_preference": "outdoor"
    }
)

response = await agent.process_query(
    "What should I pack given the weather forecast?",
    state=state
)

主要功能

• 纯客户端实现：仅关注客户端 MCP 功能，实现关注点的清晰分离
• 全局服务配置：MCP 服务配置的集中管理
• 灵活的服务选择：能够为每个客户端实例使用所有配置的服务或特定子集
• 有状态操作：内置状态管理，与 LangGraph 和类似框架无缝协作
• 类型安全：完整的 TypeScript 风格类型支持，可靠的开发体验

安装

pip install claude-mcp-agent  # Not yet published

快速开始

from claude_mcp_agent import MCPAgent, ServerConfig

# Configure global servers
servers = [
    ServerConfig(
        name="weather",
        path="/path/to/weather/server.py",
        enabled=True
    ),
    ServerConfig(
        name="database",
        path="/path/to/db/server.py",
        enabled=True
    )
]

# Create agent with all servers
agent = MCPAgent(servers=servers)

# Or create with specific servers
agent = MCPAgent(servers=servers, enabled_servers=["weather"])

# Use with state
state = {"context": "Current weather analysis"}
response = await agent.process_query("What's the weather?", state=state)

服务配置

可以通过配置文件或编程方式配置服务。

配置文件

创建一个 mcp_config.json 文件：

{
  "servers": {
    "weather": {
      "path": "/path/to/weather_server.py",
      "enabled": true,
      "env_vars": {
        "API_KEY": "${WEATHER_API_KEY}",
        "REGION": "us-west-2"
      }
    },
    "database": {
      "path": "/path/to/db_server.py",
      "enabled": true,
      "env_vars": {
        "DB_CONNECTION": "${DB_URL}"
      }
    }
  }
}

然后在代码中加载它：

from claude_mcp_agent import MCPAgent

# Load from default config path (./mcp_config.json)
agent = MCPAgent.from_config()

# Or specify config path
agent = MCPAgent.from_config("/path/to/mcp_config.json")

# Override specific servers from config
agent = MCPAgent.from_config(
    config_path="mcp_config.json",
    enabled_servers=["weather"]  # Only use weather server from config
)

编程配置

你也可以以编程方式配置服务：

from claude_mcp_agent import MCPAgent, ServerConfig

server_configs = [
    ServerConfig(
        name="weather",
        path="/path/to/weather_server.py",
        enabled=True,
        env_vars={"API_KEY": "xxx"}
    )
]

# Use programmatic configuration
agent = MCPAgent(servers=server_configs)

混合配置

你可以结合两种方法：

# Load base configuration from file
agent = MCPAgent.from_config("mcp_config.json")

# Add additional servers programmatically
additional_server = ServerConfig(
    name="new_service",
    path="/path/to/service.py",
    enabled=True
)

agent.add_server(additional_server)

状态管理

Agent 在交互之间维护状态，非常适合与 LangGraph 配合使用：

# Initialize state
state = {
    "context": "Weather analysis",
    "history": []
}

# Process query with state
response = await agent.process_query(
    "What's the weather like?",
    state=state
)

# State is updated with new context
print(state["history"])  # Shows interaction history

贡献

欢迎贡献！请阅读我们的贡献指南，了解我们的行为准则和开发流程的详细信息。