convez.ai
MCP ServerIntegração & APIsIntermediário
timseidel

formr MCP Server

timseidel/formr-mcp

Automação de pesquisas formr via linguagem natural para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra agentes de IA com o framework de pesquisas formr.org, permitindo inspeção, criação e edição de estruturas de pesquisas, gerenciamento de configurações e validação de sintaxe R através de linguagem natural. Ideal para automatizar workflows de pesquisa complexas e garantir consistência de dados.

Instalação

$npx convez-ai timseidel/formr-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Criar e gerenciar estruturas de pesquisas formr automaticamente via IA
  • Validar sintaxe R e fluxos de lógica condicional em pesquisas
  • Gerar visualizações de fluxogramas e documentação de pesquisas
  • Inspecionar e analisar consistência de itens e variáveis em runs formr

Veredito

MCP server bem estruturado para pesquisadores e analistas que usam formr.org. Oferece controle granular via API com bom suporte para validação e análise, embora exija configuração local de credenciais e conhecimento prévio do framework formr.

README

A tradução para o português deste README ainda está na fila.

formr-mcp

A Model Context Protocol server for the formr survey framework. Let LLM agents inspect, create, and edit formr run structures, manage settings, and get design guidance — all through natural language.

Prerequisites

  • Python 3.12+
  • uv — fast Python package manager
  • formr instance with admin (≥ 2) API access — create credentials at <base_url>/admin/account#api
  • R (optional) — enables R syntax validation in analyze_run

Quick Start

git clone https://github.com/timseidel/formr-mcp && cd formr-mcp
cp .env.example .env
# Edit .env with your formr instance URL and API credentials
uv sync
uv run server.py

Environment Variables

VariableDescription
FORMR_BASE_URLformr instance URL (e.g. http://localhost)
FORMR_CLIENT_ID32-char hex client ID from /admin/account#api
FORMR_CLIENT_SECRET64-char hex secret from /admin/account#api
FLOWCHART_URL(optional) URL of the formr Flowchart Generator (default: https://formr-flowchart-test.pages.dev)

MCP Client Configuration

opencode

Add to opencode.json in your project root:

{
  "mcp": {
    "formr-mcp": {
      "type": "local",
      "command": ["uv", "run", "server.py"],
      "enabled": true
    }
  }
}

Or copy from the included example:

cp opencode.json.example opencode.json

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "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

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "formr-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/formr-mcp", "server.py"]
    }
  }
}

Set FORMR_BASE_URL, FORMR_CLIENT_ID, and FORMR_CLIENT_SECRET in a .env file in the project root.

Available Tools

Run Management

ToolDescription
list_runsList all runs, optionally filter by name
get_runGet run metadata by exact name
create_runCreate a new empty run
delete_runPermanently delete a run and all its data
whoamiGet the authenticated user's profile

Structure Editing

ToolDescription
get_run_structure_to_fileFetch full structure to .formr/<name>.json (backs up existing)
update_run_structure_from_fileValidate and upload from .formr/<name>.json
update_run_settingsChange run-level settings (title, visibility, etc.)

Inspection & Analysis

ToolDescription
summarize_runHuman-readable overview (detail="units" or "items")
find_run_itemsSearch items by name/label substring and/or type
analyze_runCheck R syntax, variable refs, branch flow, item consistency
open_flowchartUpload run structure and get a shareable flowchart URL (expires in 24h)

Documentation

ToolDescription
get_documentationLearn formr design (topics: item-types, run-concepts, r-code, survey-json, examples, best-practices)
get_unit_typesGet all supported unit types and their required/optional fields
get_documentation_topicsList available documentation topics

Structure Editing Workflow

Run structures can be large. Use the file-based workflow instead of passing JSON through tool arguments:

1. Fetch   get_run_structure_to_file("my-run")
           → writes .formr/my-run.json

2. Edit    Use your editor/agent to modify .formr/my-run.json

3. Upload  update_run_structure_from_file("my-run")
           → validates, uploads, removes backup on success
  • If .formr/my-run.json already exists, the previous version is backed up to .formr/my-run.json.bak
  • On upload validation errors, fix the file and retry — restore from .bak if stuck
  • The .formr/ directory is gitignored

Project Structure

formr-mcp/
├── server.py                  # MCP server entry point, tool definitions
├── formr_mcp/
│   ├── auth.py                # OAuth2 client credentials flow
│   ├── client.py              # HTTP client for formr REST API
│   ├── documentation.py       # Built-in design documentation topics
│   ├── analysis.py            # Run structure analysis (R syntax, refs, flow)
│   ├── summarize.py           # Run summarization and item search
│   └── validation.py          # Structure validation (types, positions, choices)
├── tests/
│   ├── test_server.py         # Server and tool tests
│   ├── test_analysis.py       # Analysis module tests
│   ├── test_summarize.py       # Summarization tests
│   └── test_normalize_choices.py # Choice normalization tests
├── .env.example               # Environment variable template
├── opencode.json.example      # opencode MCP config template
└── pyproject.toml             # Project metadata and dependencies

Testing

uv run --with pytest pytest tests/

Data Protection

This server interacts with the formr admin API only. It accesses run structures, survey definitions, and settings — never participant response data. Runs are fetched and edited as structural JSON, not as data exports.

License

MIT

Ver o original no GitHub

Bom para

Relacionados