convez.ai
MCP ServerIntegração & APIsAvançado
harrytyp

Unified Research Data MCP

harrytyp/unified-researchdata-mcp

MCP unificado para pesquisa com autenticação segura por usuário

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP unificado que integra TUM DataTagger e eLabFTW atrás de um proxy reverso Caddy, com autenticação descentralizada baseada em JWT. Cada usuário registra suas credenciais pessoais sem que o servidor armazene chaves secretas, eliminando pontos únicos de falha.

Instalação

$npx convez-ai harrytyp/unified-researchdata-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
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 semanas
Versão
v1.2.0
Issues abertas
2
Contribuidores
2

Casos de uso

  • Integrar DataTagger e eLabFTW em um único endpoint MCP
  • Gerenciar múltiplos usuários com credenciais isoladas sem armazenar secrets
  • Hospedar servidores MCP em R e Python sob arquitetura unificada

Veredito

Solução arquitetural sólida para ambientes de pesquisa que precisam integrar múltiplos backends. Exige conhecimento profundo de MCP, Docker e autenticação JWT; implementação bem documentada mas voltada para administradores técnicos.

README

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

Unified Research Data MCP

License: MIT MCP Protocol Python R

Host two MCP servers — datatagger-mcp and elabrmcp (elabFTW) — behind a single Caddy reverse proxy, each with mandatory bring-your-own-API-key registration.

Server admins never configure any API keys. Every user registers their personal credentials via a web page. No secrets in .env, no shared tokens, no admin-managed keys.

MCP ServerBackendAuth Mechanism
datatagger-mcpPython / FastMCP/register → HMAC-signed JWT (no server storage)
elabrmcp (elabFTW)R / ellmer + mcptoolselabmcp-proxy → per-user R subprocess, JWT tokens

Architecture

                               ┌──────────────┐
                               │    Caddy     │
                               └──────┬───────┘
                                      │
                         ┌────────────┼────────────┐
                         ▼            ▼            │
             ┌──────────────────┐ ┌──────────────────┐
             │  datatagger-mcp  │ │  elabmcp-proxy   │
             │  port 8000       │ │  port 8081       │
             │  Python/FastMCP  │ │  Python/Starlette │
             │  /register →     │ │  /register →     │
             │  /mcp/?token=X   │ │  /mcp?token=X    │
             └──────────────────┘ └────────┬─────────┘
                                           │ spawns R subprocesses
                                           ▼
                               ┌──────────────────────┐
                               │  Rscript per session  │
                               │  elabrmcp (unmod.)    │
                               └──────────────────────┘

elabR source code is never modified. The elabmcp-proxy spawns the unmodified elabrmcp::elabr_mcp_server(type='stdio') with each user's credentials injected as environment variables. You can git pull elabR independently.


Quick Start

1. Clone repos

git clone https://github.com/harrytyp/unified-researchdata-mcp.git
cd unified-researchdata-mcp

# Clone the two MCP server dependencies alongside it
git clone https://github.com/harrytyp/datatagger-mcp.git
git clone https://github.com/MarvinLuepke/elabR.git

2. Configure

cp .env.example .env

Set your DataTagger instance URL if not using the default — no API keys go here.

3. Deploy

docker compose up -d --build

Three containers are built:

ContainerTech StackRole
unified-mcp-datatagger-mcpPython / FastMCPDataTagger MCP server
unified-mcp-elabmcp-proxyPython / FastAPI + R / ellmerelabFTW auth-proxy + per-user R subprocesses
unified-mcp-caddyCaddyTLS termination & reverse proxy

User Workflow

DataTagger

1. 👤 User visits  https://datatagger.your-domain.com/register
2. 🔑 Pastes their personal FDM_TOKEN
3. 🔗 Receives scoped URL:  https://datatagger.your-domain.com/mcp/?token=<uuid>
4. ⚙️ Registers URL in MCP client (Claude Desktop, KISSKI, etc.)

elabFTW / elabrmcp

1. 👤 User visits  https://elab.your-domain.com/register
2. 🔑 Pastes their personal ELABFTW_BASE_URL + ELABFTW_API_KEY
3. 🔗 Receives scoped URL:  https://elab.your-domain.com/mcp?token=<uuid>
4. ⚙️ Registers URL in MCP client
5. 🚀 Proxy spawns a dedicated R subprocess with those credentials
6. 🧹 After 30 minutes idle, R process is killed and memory reclaimed
7. 🪙 Token is valid for 30 days — no re-registration needed after restarts

Note: With path-based routing (single domain), replace the URLs accordingly:

  • Registration: https://yourdomain.duckdns.org/datatagger/register and https://yourdomain.duckdns.org/elab/register
  • MCP endpoints: https://yourdomain.duckdns.org/datatagger/mcp and https://yourdomain.duckdns.org/elab/mcp

DuckDNS auto-update: See docs/duckdns-setup.md for the cronjob setup to keep your domain IP current.

Caddy Configuration

Edit Caddyfile to match your domain setup.

Option 1: Two subdomains (recommended for production)

Replace your-domain.com with your actual domain:

datatagger.your-domain.com { ... }
elab.your-domain.com       { ... }

Option 2: Single domain with path-based routing (e.g., DuckDNS)

If you only have one domain (like a DuckDNS subdomain), use handle_path to strip the prefix:

yourdomain.duckdns.org {
    handle_path /datatagger/* {
        reverse_proxy datatagger-mcp:8000
    }

    handle_path /elab/* {
        reverse_proxy elabmcp-proxy:8081
    }
}

Then access:

  • DataTagger registration: https://yourdomain.duckdns.org/datatagger/register
  • elabFTW registration: https://yourdomain.duckdns.org/elab/register

Local testing without DNS

Access the containers directly:

ServiceURL
DataTagger registrationhttp://localhost:8000/register
elabFTW registrationhttp://localhost:8081/register

elabmcp-proxy

The elabmcp-proxy is a Python / FastAPI service that adds per-user authentication in front of elabrmcp without modifying its source code.

elabmcp-proxy/
├── Dockerfile              # R + elabR + elabrmcp + Python proxy
├── requirements.txt
├── pyproject.toml
└── src/elabmcp_proxy/
    ├── __init__.py
    ├── __main__.py         # Entry point
    ├── app.py              # FastAPI: /register, SSE↔stdio bridge
    └── session.py          # Per-user R subprocess lifecycle

How it works

  1. Registration -- user enters credentials into web form -> server creates an HMAC-SHA256 JWT embedding the credentials (no server-side storage)
  2. R subprocess spawn -- first POST /mcp?token=X spawns Rscript -e "elabrmcp::elabr_mcp_server(type='stdio')" with credentials as env vars
  3. Bridge -- proxy translates MCP SSE events <-> stdio JSON-RPC lines via asyncio subprocess
  4. Isolation -- each user gets a separate R process, no shared state
  5. Cleanup -- processes killed after 30 minutes of inactivity

Transport: stdio (not HTTP)

The R subprocess uses type='stdio' transport. This avoids a critical bug in R's HTTP backend (type='http') which alternates between returning HTTP 200 and 202 for consecutive requests. This alternating behavior breaks any MCP client using Streamable HTTP (like Hermes Agent).

TransportStatusIssue
type='http'BrokenR alternates 200/202 per request. proxy_request retries all get 202, client gets 502
type='stdio'WorkingR reads JSON-RPC from stdin, writes to stdout. No HTTP layer = no 200/202

The stdio read timeout is 120s (configurable via ELABMCP_STDIO_TIMEOUT) to handle cold-start R package loading.

Do NOT add a warmup/health-check request during ensure_running() -- sending any request to R during startup creates a session collision. Even an empty POST body can leave R in a bad state.

Known issues

  • Container restart wipes sessions: FIXED — tokens are now self-contained JWTs signed with MCP_JWT_SECRET. Container restarts do NOT invalidate tokens. 30-day expiry.
  • Response timeout: If R takes >120s to respond via stdout, the proxy returns 504. Increase ELABMCP_STDIO_TIMEOUT if needed.

Running tests### Running tests

cd elabmcp-proxy
pip install -e ".[dev]"
pytest tests/ -v

# Docker integration tests (requires running containers):
DOCKER_TESTS=1 pytest tests/test_docker_services.py -v

Security Audit

📋 Full changelog: CHANGELOG.md

Current posture

AspectStatusDetails
No admin-managed secrets✅.env contains no API keys
Per-user isolation✅Each user gets an OS-level R subprocess
Session expiry✅30-minute inactivity (R process), 30-day token lifetime
In-transit encryption✅Terminated by Caddy (TLS)
Rate limiting✅slowapi, 10 POST/min per IP
Subprocess resource caps✅RLIMIT_AS (256 MB), RLIMIT_CPU (300 s), RLIMIT_NPROC (64), global max 20 sessions
Audit logging✅Structured log at ELABMCP_AUDIT_LOG
Graceful shutdown✅SIGTERM → 3 s wait → SIGKILL
Docker resource limits✅Per-container mem_limit + stop_grace_period
Token-based auth✅HMAC-SHA256 JWTs, self-contained, no server storage
No persistent secrets✅JWTs are self-contained, no server-side credential storage
Test coverage✅40 pytest + 15 Docker integration tests

Remaining areas

🟡 Medium priority

  1. Token transmission in URL — session tokens are passed as URL query parameters (/mcp?token=X). This exposes tokens in:

    • Server access logs
    • Browser history (if user visits the URL manually)
    • Referer headers
    • Consider moving the token to a header (Authorization: Bearer X) or a cookie
  2. HTTPS-only enforcement — Caddy handles TLS, but the proxy containers also accept plain HTTP on their internal ports. A middleware should reject non- HTTPS requests (or rely on Caddy stripping them).

🟢 Low priority

  1. Subprocess isolation — all R subprocesses share the same Linux user inside the container. For stronger isolation, consider spawning each R process in a separate Docker container or using nsjail.

  2. Subprocess restart on crash — if an R subprocess crashes, the SSE connection to the user drops and the session becomes unusable. The proxy could detect the crash and automatically re-spawn the subprocess for reconnect attempts.

  3. Memory-only credential lifetime — credentials are stored in plain-text Python dicts. For advanced deployments, consider encrypting them at rest with a server-side key.


Dependencies

ComponentRepositoryRole
elabR / elabrmcpExternalelabFTW R API client + MCP server
datatagger-mcpExternalDataTagger MCP server
ellmerCRANR MCP client library
mcptoolsCRANR MCP transport layer
FastAPIPyPIPython web framework (elabmcp-proxy)
CaddyExternalTLS reverse proxy
DockerExternalContainer runtime
MCP ProtocolSpecificationModel Context Protocol

License

This project is licensed under the MIT License. The dependency repos (elabR, datatagger-mcp) are governed by their respective licenses.

Ver o original no GitHub

Bom para

Relacionados