🐑 牧羊人MCP
Shepherd的MCP（模型上下文协议）服务器-像调试代码一样调试AI代理。
此MCP服务器允许AI助手（Claude、Cursor等）查询和分析来自多个可观察性提供者的AI代理会话。
支持的提供商
- AIOBS （Shepherd后端）-本地Shepherd可观察性
- 廊坊 -开源LLM可观测性平台
安装
pip install shepherd-mcp或者直接用uvx运行：
uvx shepherd-mcp配置
环境变量
AIOBS（牧羊人）
AIOBS_API_KEY（必需）-您的Shepherd API密钥AIOBS_ENDPOINT（可选）-自定义API端点URL
廊坊
LANGFUSE_PUBLIC_KEY（必需）-您的Langfuse公共API密钥LANGFUSE_SECRET_KEY（必需）-您的Langfuse机密API密钥LANGFUSE_HOST（可选）-自定义Langfuse主机URL（默认为cloud.Langfuse.com）
.env文件支持
牧羊人mcp自动加载 .env 当前目录或任何父目录中的文件。这意味着如果你有 .env 项目根目录中的文件：
# .env
# AIOBS
AIOBS_API_KEY=aiobs_sk_xxxx
# Langfuse
LANGFUSE_PUBLIC_KEY=pk-lf-xxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxx
LANGFUSE_HOST=https://cloud.langfuse.comMCP服务器启动时，它将自动加载。
克劳德桌面
添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"shepherd": {
"command": "uvx",
"args": ["shepherd-mcp"],
"env": {
"AIOBS_API_KEY": "aiobs_sk_xxxx",
"LANGFUSE_PUBLIC_KEY": "pk-lf-xxxx",
"LANGFUSE_SECRET_KEY": "sk-lf-xxxx",
"LANGFUSE_HOST": "https://cloud.langfuse.com"
}
}
}
}光标
添加到您的 .cursor/mcp.json:
{
"mcpServers": {
"shepherd": {
"command": "uvx",
"args": ["shepherd-mcp"],
"env": {
"AIOBS_API_KEY": "aiobs_sk_xxxx",
"LANGFUSE_PUBLIC_KEY": "pk-lf-xxxx",
"LANGFUSE_SECRET_KEY": "sk-lf-xxxx",
"LANGFUSE_HOST": "https://cloud.langfuse.com"
}
}
}
}或者，如果通过pip安装：
{
"mcpServers": {
"shepherd": {
"command": "shepherd-mcp",
"env": {
"AIOBS_API_KEY": "aiobs_sk_xxxx",
"LANGFUSE_PUBLIC_KEY": "pk-lf-xxxx",
"LANGFUSE_SECRET_KEY": "sk-lf-xxxx",
"LANGFUSE_HOST": "https://cloud.langfuse.com"
}
}
}
}可用工具
AIOBS（牧羊犬）工具
aiobs_list_sessions
列出Shepherd的所有AI代理会话。
参数：
limit（可选）：要返回的最大会话数
示例提示：
“列出我最近从AIOBS获得的AI代理会话”
aiobs_get_session
获取特定会话的详细信息，包括完整的跟踪树、LLM调用、函数事件和评估。
参数：
session_id（必填）：要检索的会话的UUID
示例提示：
“获取abc123-def456的AIOBS会话详细信息”
aiobs_search_sessions
使用多个条件搜索和筛选会话。
参数：
query（可选）：文本搜索（匹配名称、ID、标签、元数据）labels（可选）：按标签作为键值对进行筛选provider（可选）：按LLM提供者筛选（例如，“openai”、“anthropic”）model（可选）：按型号名称过滤（例如，“gpt-4o-mini”、“claude-3”）function（可选）：按函数名称筛选after（可选）：会话在日期（YYYY-MM-DD）之后开始before（可选）：会话在日期（YYYY-MM-DD）之前开始has_errors（可选）：仅返回有错误的会话evals_failed（可选）：仅返回评估失败的会话limit（可选）：要返回的最大会话数
示例提示：
“查找所有使用OpenAI但有错误的AIOBS会话” “搜索昨天未通过评估的会话”
aiobs_diff_sessions
比较两个会话并显示它们的差异，包括：
- 元数据：持续时间、标签、时间戳
- LLM电话：计数、令牌（输入/输出/总计）、平均延迟、错误
- 供应商/型号分布：使用了哪些提供商和模型
- 功能事件：总调用数、唯一函数数、特定函数计数
- 跟踪结构：跟踪深度，根节点
- 评估：通过/失败计数和比率
- 系统提示：比较会话之间的系统提示
- 请求参数：温度、max_tokens、使用的工具
- 响应内容：内容长度、工具调用、停止原因
参数：
session_id_1（必需）：要比较的第一个会话UUIDsession_id_2（必需）：要比较的第二个会话UUID
示例提示：
“比较AIOBS会话abc123和def456”
______________________________________________________________________
Langfuse工具
langfuse_list_traces
使用分页和过滤器列出跟踪。痕迹代表完整的工作流程或对话。
参数：
limit（可选）：每页最大结果数（默认值：50）page（可选）：页码（1-索引）user_id（可选）：按用户ID筛选name（可选）：按跟踪名称筛选session_id（可选）：按会话ID筛选tags（可选）：按标签筛选from_timestamp（可选）：时间戳后过滤to_timestamp（可选）：在时间戳之前过滤
示例提示：
“列出最后20条廊坊痕迹”
langfuse_get_trace
通过其观察结果（世代、跨度、事件）获取特定的跟踪。
参数：
trace_id（必填）：要获取的跟踪ID
示例提示：
“获取trace-id-123的Langfuse跟踪详细信息”
langfuse_list_sessions
列出带分页的会话。会话将相关痕迹分组在一起。
参数：
limit（可选）：每页最大结果数page（可选）：页码from_timestamp（可选）：时间戳后过滤to_timestamp（可选）：在时间戳之前过滤
示例提示：
“向我展示上周的Langfuse会话”
langfuse_get_session
获取具有指标和跟踪的特定会话。
参数：
session_id（必填）：要获取的会话ID
示例提示：
“获取会话-123的Langfuse会话详细信息”
langfuse_list_observations
使用过滤器列出观察结果（世代、跨度、事件）。
参数：
limit（可选）：每页最大结果数page（可选）：页码name（可选）：按观测名称筛选user_id（可选）：按用户ID筛选trace_id（可选）：按跟踪ID筛选type（可选）：按类型筛选（生成、跨度、事件）from_timestamp（可选）：时间戳后过滤to_timestamp（可选）：在时间戳之前过滤
示例提示：
“列出Langfuse的所有GENERATION类型观测值”
langfuse_get_observation
获得一个具体的观察结果，包括输入、输出、使用和成本等全部细节。
参数：
observation_id（必填）：要获取的观察ID
示例提示：
“获取Langfuse obs-123观测的详细信息”
langfuse_list_scores
使用过滤器列出分数/评估。
参数：
limit（可选）：每页最大结果数page（可选）：页码name（可选）：按分数名称筛选user_id（可选）：按用户ID筛选trace_id（可选）：按跟踪ID筛选from_timestamp（可选）：时间戳后过滤to_timestamp（可选）：在时间戳之前过滤
示例提示：
“显示Langfuse的痕迹-123分数”
langfuse_get_score
获得详细的具体分数/评估。
参数：
score_id（必填）：要获取的分数ID
示例提示：
“获取分数123的Langfuse分数详细信息”
______________________________________________________________________
旧版工具（已弃用）
为了向后兼容，以下工具仍然可用，但将在未来的版本中删除：
list_sessions→ Useaiobs_list_sessionsget_session→ Useaiobs_get_sessionsearch_sessions→ Useaiobs_search_sessionsdiff_sessions→ Useaiobs_diff_sessions
用例
1.调试失败的运行
“显示过去24小时内出现错误的所有AIOBS会话”
2.性能分析
“将AIOBS会话abc123与会话def456进行比较，并告诉我哪一个更有效”
3.快速回归检测
“查找评估失败的Langfuse痕迹”
4.成本跟踪
“列出Langfuse的观察结果并总结总成本”
5.会议检查
“获取最近Langfuse跟踪的完整跟踪树，并解释发生了什么”
6.跨提供商分析
“向我展示AIOBS会议和Langfuse今天的记录”
发展
设置
git clone https://github.com/neuralis/shepherd-mcp
cd shepherd-mcp
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"运行测试
pytest本地运行
export AIOBS_API_KEY=aiobs_sk_xxxx
export LANGFUSE_PUBLIC_KEY=pk-lf-xxxx
export LANGFUSE_SECRET_KEY=sk-lf-xxxx
python -m shepherd_mcp发布到PyPI
创建发布时，发布会通过GitHub Actions自动发布到PyPI。
要手动发布，请执行以下操作：
# Build the package
pip install build twine
python -m build
# Upload to PyPI
twine upload dist/*建筑
src/shepherd_mcp/
├── __init__.py # Package exports
├── __main__.py # Entry point
├── server.py # MCP server with tool handlers
├── models/ # Data models
│ ├── __init__.py
│ ├── aiobs.py # AIOBS-specific models
│ └── langfuse.py # Langfuse-specific models
└── providers/ # Provider clients
├── __init__.py
├── base.py # Base provider interface
├── aiobs.py # AIOBS client implementation
└── langfuse.py # Langfuse client implementation┌─────────────────┐ stdio ┌─────────────────┐
│ Cursor/Claude │ ◄────────────► │ shepherd-mcp │
│ (Client) │ stdin/stdout │ (subprocess) │
└─────────────────┘ └────────┬────────┘
│ HTTPS
┌─────────┴─────────┐
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Shepherd API│ │ Langfuse API│
│ (AIOBS) │ │ (Cloud) │
└─────────────┘ └─────────────┘许可证
麻省理工学院