内容
# epicstaff-mcp
MCP 服务器，用于 [EpicStaff](https://github.com/EpicStaff/EpicStaff) — 通过 Claude、Cursor 和任何与 MCP 兼容的工具控制您的 AI 代理、流程、团队和知识库。
## 要求
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)（推荐）或 pip
- 运行中的 EpicStaff 实例
- GitHub 访问权限
## 安装
### 使用 uv（推荐 — 无需手动安装）
`uvx` 直接从私有仓库拉取并运行软件包：
```bash
uvx --from git+https://github.com/EpicStaff/epicstaff-mcp.git epicstaff-mcp
```
### 使用 pip
```bash
pip install git+https://github.com/EpicStaff/epicstaff-mcp.git
```
> **私有仓库访问：** 确保您的 GitHub 凭证或 SSH 密钥已配置，以便 `git clone` 可以访问此仓库。在 macOS 上，`gh auth login` 是最简单的方法。
## Claude 代码
### 作为插件（推荐 — 工具和技能）
作为插件安装会将 MCP 工具和捆绑的技能（/skills → 流程构建、DDD 设计、QA、调试、EpicChat 输出）一起上线：
```
/plugin marketplace add EpicStaff/epicstaff-mcp
/plugin install epicstaff-mcp@epicstaff
```
在您的 shell 配置文件中设置 `EPICSTAFF_BASE_URL`（和可选的 `EPICSTAFF_API_TOKEN`），以便捆绑的 MCP 服务器可以访问您的实例。
### 作为裸 MCP 服务器（仅工具 — 无技能）
如果您只想要工具而不要技能：
```bash
claude mcp add epicstaff \
-e EPICSTAFF_BASE_URL=http://localhost:8000 \
-e EPICSTAFF_API_TOKEN=your-token \
-- uvx --from git+https://github.com/EpicStaff/epicstaff-mcp.git epicstaff-mcp
```
> 裸 MCP 服务器永远不会加载 `skills/` 目录 — 这就是为什么上面的插件路径是推荐的，如果您想要 EpicStaff 工作流程。
参见 [CLAUDE.md](CLAUDE.md) 以获取完整的 Claude Code 设置说明。
## Claude 桌面版
添加到 `claude_desktop_config.json`（macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"epicstaff": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/EpicStaff/epicstaff-mcp.git",
"epicstaff-mcp"
],
"env": {
"EPICSTAFF_BASE_URL": "http://localhost:8000",
"EPICSTAFF_API_TOKEN": "your-token-here"
}
}
}
}
```
## Cursor
在 `.cursor/mcp.json` 中：
```json
{
"mcpServers": {
"epicstaff": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/EpicStaff/epicstaff-mcp.git",
"epicstaff-mcp"
],
"env": {
"EPICSTAFF_BASE_URL": "http://localhost:8000",
"EPICSTAFF_API_TOKEN": "your-token-here"
}
}
}
}
```
## 配置
所有设置均从环境变量（前缀：`EPICSTAFF_`）中读取：
| 变量 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|
| `EPICSTAFF_BASE_URL` | 是 | — | 您的 EpicStaff 实例的基本 URL，例如 `http://localhost:8000` |
| `EPICSTAFF_API_TOKEN` | 否 | — | API 密钥身份验证的 Bearer 令牌 |
| `EPICSTAFF_USERNAME` | 否 | — | 基本身份验证的用户名（必须与 `EPICSTAFF_PASSWORD` 配对） |
| `EPICSTAFF_PASSWORD` | 否 | — | 基本身份验证的密码 |
| `EPICSTAFF_TIMEOUT` | 否 | `30.0` | 秒为单位的 HTTP 请求超时时间 |
| `EPICSTAFF_MAX_RETRIES` | 否 | `3` | 暂时错误时的重试次数 |
设置 `EPICSTAFF_API_TOKEN` **或** `EPICSTAFF_USERNAME`/`EPICSTAFF_PASSWORD` — 而不是两者。
## 可用工具
### 代理
| 工具 | 描述 |
|---|---|
| `list_agents` | 列出所有代理（分页 + 搜索） |
| `get_agent` | 按 ID 获取代理详细信息 |
| `create_agent` | 创建新代理 |
| `update_agent` | 更新现有代理 |
| `delete_agent` | 删除代理 |
### 团队
| 工具 | 描述 |
|---|---|
| `list_crews` | 列出所有团队 |
| `get_crew` | 按 ID 获取团队详细信息 |
| `create_crew` | 创建新团队并分配代理 |
| `update_crew` | 更新现有团队 |
| `delete_crew` | 删除团队 |
### 流程
| 工具 | 描述 |
|---|---|
| `list_flows` | 列出所有流程（轻量级，无节点详细信息） |
| `get_flow` | 获取具有所有节点和边的完整流程 |
| `create_flow` | 创建新的空流程 |
| `update_flow_metadata` | 更新流程名称/描述/设置 |
| `get_flow_nodes` | 按类型列出流程中的所有节点 |
| `add_node` | 向流程添加节点 |
| `update_node` | 更新节点的配置 |
| `delete_node` | 从流程中删除节点 |
| `list_edges` | 列出流程的边和条件边 |
| `add_edge` | 用边连接两个节点 |
| `delete_edge` | 删除边 |
### 会话
| 工具 | 描述 |
|---|---|
| `list_sessions` | 列出流程的会话 |
| `run_session` | 为流程启动新会话 |
| `get_session_updates` | 轮询会话输出和状态 |
| `stop_session` | 停止正在运行的会话 |
| `send_message` | 向等待人类输入的会话发送消息 |
### 工具
| 工具 | 描述 |
|---|---|
| `list_tools` | 列出所有 MCP 和 Python 代码工具 |
| `get_tool` | 按 ID 获取工具详细信息 |
| `create_mcp_tool` | 添加新的 MCP 工具连接 |
| `create_python_tool` | 添加新的 Python 代码工具 |
| `update_mcp_tool` | 更新现有的 MCP 工具 |
| `update_python_tool` | 更新现有的 Python 代码工具 |
| `delete_tool` | 删除工具 |
### 知识（RAG）
| 工具 | 描述 |
|---|---|
| `list_source_collections` | 列出所有知识集合 |
| `create_source_collection` | 创建新的知识集合 |
| `add_document` | 向集合添加文档 |
| `trigger_rag_indexing` | 触发嵌入和向量索引 |
### LLM 配置
| 工具 | 描述 |
|---|---|
| `list_llm_configs` | 列出所有 LLM 配置 |
| `get_llm_config` | 按 ID 获取 LLM 配置 |
| `create_llm_config` | 创建新的 LLM 配置 |
| `update_llm_config` | 更新现有的 LLM 配置 |
| `delete_llm_config` | 删除 LLM 配置 |
| `list_embedding_configs` | 列出所有嵌入配置 |
| `create_embedding_config` | 创建新的嵌入配置 |
### 健康和配置
| 工具 | 描述 |
|---|---|
| `ping` | 检查 EpicStaff 是否可达 |
| `list_providers` | 列出可用的 LLM 提供商 |
## 许可证
MIT
