内容
# formr-mcp
一个适用于 [formr](https://formr.org) 调查框架的 [模型上下文协议](https://modelcontextprotocol.io) 服务器。让 LLM 代理检查、创建和编辑 formr 运行结构，管理设置，并获得设计指导 — 所有这些都通过自然语言。
## 前提条件
- **Python 3.12+**
- **[uv](https://docs.astral.sh/uv/)** — 快速的 Python 包管理器
- **formr 实例**，具有管理员（≥ 2）API 访问权限 — 在 `<base_url>/admin/account#api` 处创建凭证
- **R**（可选）— 在 `analyze_run` 中启用 R 语法验证
## 快速入门
```bash
git clone https://github.com/timseidel/formr-mcp && cd formr-mcp
cp .env.example .env
# 使用您的 formr 实例 URL 和 API 凭证编辑 .env
uv sync
uv run server.py
```
### 环境变量
| 变量 | 描述 |
|---|---|
| `FORMR_BASE_URL` | formr 实例 URL（例如 `http://localhost`） |
| `FORMR_CLIENT_ID` | 来自 `/admin/account#api` 的 32 位十六进制客户端 ID |
| `FORMR_CLIENT_SECRET` | 来自 `/admin/account#api` 的 64 位十六进制密钥 |
| `FLOWCHART_URL` | （可选）formr Flowchart Generator 的 URL（默认：`https://formr-flowchart-test.pages.dev`） |
## MCP 客户端配置
### opencode
在项目根目录中添加到 `opencode.json` 中：
```json
{
"mcp": {
"formr-mcp": {
"type": "local",
"command": ["uv", "run", "server.py"],
"enabled": true
}
}
}
```
或从包含的示例中复制：
```bash
cp opencode.json.example opencode.json
```
### Claude Desktop
添加到 `claude_desktop_config.json`（macOS: `~/Library/Application Support/Claude/`，Windows: `%APPDATA%\Claude\`）：
```json
{
"mcpServers": {
"formr-mcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/formr-mcp", "server.py"],
"env": {
"FORMR_BASE_URL": "http://localhost",
"FORMR_CLIENT_ID": "your_client_id",
"FORMR_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
### Cursor
在项目中添加到 `.cursor/mcp.json` 中：
```json
{
"mcpServers": {
"formr-mcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/formr-mcp", "server.py"]
}
}
}
```
在项目根目录的 `.env` 文件中设置 `FORMR_BASE_URL`、`FORMR_CLIENT_ID` 和 `FORMR_CLIENT_SECRET`。
## 可用工具
### 运行管理
| 工具 | 描述 |
|---|---|
| `list_runs` | 列出所有运行，可选按名称过滤 |
| `get_run` | 按确切名称获取运行元数据 |
| `create_run` | 创建新的空运行 |
| `delete_run` | 永久删除运行及其所有数据 |
| `whoami` | 获取已认证用户的个人资料 |
### 结构编辑
| 工具 | 描述 |
|---|---|
| `get_run_structure_to_file` | 获取完整的结构到 `.formr/<name>.json`（备份现有） |
| `update_run_structure_from_file` | 从 `.formr/<name>.json` 验证和上传 |
| `update_run_settings` | 更改运行级设置（标题、可见性等） |
### 检查与分析
| 工具 | 描述 |
|---|---|
| `summarize_run` | 人类可读的概述（`detail="units"` 或 `"items"`） |
| `find_run_items` | 按名称/标签子字符串和/或类型搜索项目 |
| `analyze_run` | 检查 R 语法、变量引用、分支流程、项目一致性 |
| `open_flowchart` | 上传运行结构并获取可共享的流程图 URL（24 小时后过期） |
### 文档
| 工具 | 描述 |
|---|---|
| `get_documentation` | 学习 formr 设计（主题：`item-types`、`run-concepts`、`r-code`、`survey-json`、`examples`、`best-practices`） |
| `get_unit_types` | 获取所有支持的单元类型及其必填/可选字段 |
| `get_documentation_topics` | 列出可用的文档主题 |
## 结构编辑工作流程
运行结构可能很大。使用 **基于文件的流程** 而不是通过工具参数传递 JSON：
```
1. 获取 get_run_structure_to_file("my-run")
→ 写入 .formr/my-run.json
2. 编辑 使用您的编辑器/代理修改 .formr/my-run.json
3. 上传 update_run_structure_from_file("my-run")
→ 验证，上传，在成功后删除备份
```
- 如果 `.formr/my-run.json` 已经存在，则将先前版本备份到 `.formr/my-run.json.bak`
- 在上传验证错误时，修复文件并重试 — 如果卡住，从 `.bak` 恢复
- `.formr/` 目录被 gitignore
## 项目结构
```
formr-mcp/
├── server.py # MCP 服务器入口点，工具定义
├── formr_mcp/
│ ├── auth.py # OAuth2 客户端凭证流程
│ ├── client.py # formr REST API 的 HTTP 客户端
│ ├── documentation.py # 内置设计文档主题
│ ├── analysis.py # 运行结构分析（R 语法，引用，流程）
│ ├── summarize.py # 运行总结和项目搜索
│ └── validation.py # 结构验证（类型，位置，选择）
├── tests/
│ ├── test_server.py # 服务器和工具测试
│ ├── test_analysis.py # 分析模块测试
│ ├── test_summarize.py # 总结测试
│ └── test_normalize_choices.py # 选择归一化测试
├── .env.example # 环境变量模板
├── opencode.json.example # opencode MCP 配置模板
└── pyproject.toml # 项目元数据和依赖项
```
## 测试
```bash
uv run --with pytest pytest tests/
```
## 数据保护
此服务器仅与 formr **管理员 API** 交互。它访问运行结构、调查定义和设置 — **从不访问参与者响应数据**。运行被获取和编辑为结构化 JSON，而不是数据导出。
## 许可证
MIT
