better-mcp 🚀

El puente definitivo entre agentes de IA y tu proyecto.

better-mcp es un MCP server universal que cualquier agente (Hermes, Claude Code, Cursor, Copilot, Cline, cualquier cliente MCP) puede usar para interactuar con tu proyecto como un desarrollador humano, pero más rápido y sin fricción.

# Una vez instalado, cualquier agente conectado puede:
npx better-mcp run              # Modo stdio (default)
npx better-mcp --http --port 3100  # Modo HTTP con SSE
# → tools: fs_*, db_*, shell_*, git_*, project_*, workspace_*, auth_*, plugin_*

---

¿Por qué better-mcp?

Hoy, los agentes de IA interactúan con proyectos de formas ad-hoc y frágiles:

❌ "ssh a este server, haz docker compose exec db psql, corre esta query"
❌ "escribe el archivo, pero hazlo via heredoc SSH y espera que no se corrompa"
❌ "tsc pasa? no sé, pregúntale al usuario"
❌ "¿cuál era el estado del proyecto? lee 5 archivos y adivina"

Con better-mcp, el agente solo pregunta:

✅ fs_read("src/app/page.tsx")
✅ db_query("SELECT count(*) FROM orders")
✅ shell_run("tsc")
✅ git_status()
✅ project_info()

Un solo punto de entrada. Estructurado. Ejecutable. Sin ambigüedad.

---

¿Qué problema resuelve?

| Problema | Sin better-mcp | Con better-mcp | |---|---|---| | Escribir código | heredoc SSH corrompe strings con quotes/backticks/${} | fs_write(path, content) — escaping correcto automático | | Consultar DB | Saber URL, usuario, contraseña, wrapper docker | db_query("SELECT...") — SQL read-only, conexión gestionada | | Correr tests/build | ssh → cd /repo → npx tsc... (comandos exactos que el agente adivina) | shell_run("tsc") — comandos definidos en config | | Saber estado | Preguntar al usuario o hacer 5 comandos separados | project_info() + git_status() = contexto completo en 2 calls | | Deploy | Script manual, pasos olvidados, migraciones en orden incorrecto | shell_run("deploy") — secuencia definida, autorizable | | Contexto inicial | Leer 10 archivos para entender el proyecto | read_resource("handoff") + project_info() = onboarding instantáneo | | Multi-agente | Cada agente aprende los comandos por separado | Misma interfaz MCP para todos | | Seguridad | Gates de permisos bloquean comandos válidos | El MCP es el único canal autorizado, control granular |

---

Quick Start

1. Instalar

# Global (recomendado)
npm install -g @erquier/better-mcp

# O via npx (sin instalación)
npx @erquier/better-mcp run

2. (Opcional) Generar better-mcp.json

No hace falta configurar nada para empezar. Si no hay better-mcp.json, better-mcp auto-detecta el proyecto desde el directorio actual: root = cwd, el repo como sandbox de filesystem, los scripts de package.json como shell.commands, DATABASE_URL (si es Postgres) como DB read-only, y README/schema/handoff como recursos. Es realmente _agregar y usar_, sin imágenes ni setup.

Para personalizar, generá un config pre-rellenado y editalo:

npx @erquier/better-mcp init   # escanea el cwd y escribe better-mcp.json

Config completo de ejemplo — agregá los tool groups que necesites:

{
  "$schema": "https://raw.githubusercontent.com/erquier/better-mcp/main/better-mcp.schema.json",
  "project": "mi-app",
  "root": "/path/to/project",
  "stack": ["nextjs", "prisma", "postgres", "docker"],
  "tools": {
    "fs": {
      "allowedPaths": ["/path/to/project"],
      "maxFileSize": 10485760
    },
    "db": {
      "url": "${DATABASE_URL}",
      "readOnly": true,
      "schemas": ["public"],
      "maxRows": 500
    },
    "shell": {
      "commands": {
        "tsc": "npx tsc --noEmit",
        "build": "docker compose build",
        "test": "pnpm test",
        "lint": "pnpm lint",
        "deploy": "./scripts/deploy.sh"
      },
      "allowRaw": false
    },
    "git": {
      "enabled": true,
      "maxCommits": 50
    }
  },
  "resources": {
    "handoff": "HANDOFF.md",
    "docs": "docs/",
    "schema": "prisma/schema.prisma"
  }
}

3. Conectarlo desde cualquier cliente MCP

Hermes Agent (~/.hermes/config.yaml): ``yaml mcp: servers: mi-proyecto: command: npx args: ["@erquier/better-mcp", "run"] env: DATABASE_URL: "postgresql://user:pass@localhost:5432/mydb" ``

Claude Desktop (claude_desktop_config.json): ``json { "mcpServers": { "mi-proyecto": { "command": "npx", "args": ["@erquier/better-mcp", "run"], "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" } } } } ``

Cursor / Cline / Cualquier cliente MCP: mismo patrón.

4. Usar las tools desde cualquier agente

Una vez conectado, el agente puede llamar: `` ▶ fs_read("src/app/page.tsx") ▶ shell_run("tsc") ▶ db_query("SELECT id, name FROM products LIMIT 5") ▶ git_status() ▶ project_info() ``

---

Tools disponibles — API completa

📁 Filesystem (fs_*)

Requiere tools.fs en la config.

| Tool | Input | Returns | Descripción | |---|---|---|---| | fs_read(path, offset?, limit?) | path: string, offset?: number (1-indexed, default 1), limit?: number (max 2000, default 500) | { content, totalLines, fileSize } | Lee archivo con paginación automática. Bloquea path traversal. | | fs_write(path, content) | path: string, content: string | { path, bytesWritten } | Escribe archivo (escaping correcto). Crea directorios. Límite 10MB. | | fs_search(pattern, fileGlob?, limit?) | pattern: string (regex, max 500 chars), fileGlob?: string, limit?: number (max 500, default 50) | { matches: [{ file, line, content }] } | Grep regex en el proyecto. Usa rg (ripgrep). | | fs_list(path) | path: string | [{ name, type: "file"\|"dir"\|"symlink", size }] | Lista contenido del directorio (máx 10,000 entries). |

Ejemplos de output

fs_read("package.json", 1, 5): ``json { "content": "{\n \"name\": \"@erquier/better-mcp\",\n \"version\": \"0.1.0\",\n \"description\": \"MCP server universal...\",\n \"type\": \"module\"", "totalLines": 55, "fileSize": 1116 } ``

fs_write("test.txt", "hello world"): ``json { "path": "/tmp/better-mcp/test.txt", "bytesWritten": 11 } ``

*fs_search("import", ".ts")**: ``json { "matches": [ { "file": "src/server.ts", "line": 1, "content": "import { Server } from \"@modelcontextprotocol/sdk/server/index.js\";" }, { "file": "src/config.ts", "line": 1, "content": "import { readFileSync, existsSync } from \"fs\";" } ] } ``

fs_list("."): ``json [ { "name": "src", "type": "dir", "size": 4096 }, { "name": "package.json", "type": "file", "size": 1116 }, { "name": "tsconfig.json", "type": "file", "size": 390 } ] ``

🗄️ Database (db_*)

Requiere tools.db en la config y psql instalado.

| Tool | Input | Returns | Descripción | |---|---|---|---| | db_query(sql) | sql: string (SELECT/WITH only en read-only, max 100K chars) | { columns, rows, rowCount, truncated } | SQL read-only, resultados paginados (LIMIT automático). | | db_schema(schemas?) | schemas?: string[] (filtro, default: config o ["public"]) | { tables: [{ schema, name, columns, indexes, rowCountEstimate }] } | Schema completo: tablas, columnas, tipos, nullable, defaults, primary keys. |

Seguridad

• Read-only por defecto: solo SELECT y WITH en modo read-only.
• Sanitización: validación de schema names contra inyección SQL.
• URL validation: solo URLs que comiencen con postgres:// o postgresql://.
• Límite de query: max 100,000 caracteres.

Ejemplos de output

db_query("SELECT id, name, email FROM users LIMIT 3"): ``json { "columns": ["id", "name", "email"], "rows": [ { "id": "1", "name": "Alice", "email": "alice@example.com" }, { "id": "2", "name": "Bob", "email": "bob@example.com" }, { "id": "3", "name": "Charlie", "email": "charlie@example.com" } ], "rowCount": 3, "truncated": false } ``

db_schema(): ``json { "tables": [ { "schema": "public", "name": "users", "columns": [ { "name": "id", "type": "integer", "nullable": false, "default": "nextval('users_id_seq'::regclass)", "isPrimaryKey": true }, { "name": "name", "type": "character varying", "nullable": false, "default": null, "isPrimaryKey": false }, { "name": "email", "type": "character varying", "nullable": false, "default": null, "isPrimaryKey": false } ], "indexes": [], "rowCountEstimate": 0 } ] } ``

🖥️ Shell (shell_*)

Requiere tools.shell en la config.

| Tool | Input | Returns | Descripción | |---|---|---|---| | shell_run(command) | command: string (nombre del comando, max 100 chars) | { stdout, stderr, exitCode, duration } | Ejecuta comando predefinido de la config. | | shell_raw(command, timeout?) | command: string (max 10K chars), timeout?: number (default 120s, max 3600s) | { stdout, stderr, exitCode, duration } | Comando shell arbitrario (solo si allowRaw: true). |

Seguridad

• Whitelist: shell_run solo ejecuta comandos definidos en commands.
• Raw validation: shell_raw bloquea backticks ( ) y newlines para evitar inyección.
• Límite de output: max 10MB.
• Variables de entorno: PROJECT_ROOT se inyecta automáticamente.
• Timeout: default 5 min para shell_run, 2 min para shell_raw.

Ejemplos de output

shell_run("test") (con config "test": "echo 'tests ok'"): ``json { "stdout": "tests ok", "stderr": "", "exitCode": 0, "duration": 45 } ``

shell_run("fail") (con config "fail": "exit 1"): ``json { "stdout": "", "stderr": "", "exitCode": 1, "duration": 12 } ``

🔗 Git (git_*)

Habilitado por defecto. Requiere que el proyecto sea un repositorio git.

| Tool | Input | Returns | Descripción | |---|---|---|---| | git_status() | — | { branch, isClean, staged[], unstaged[], untracked[], ahead, behind, lastCommit } | Branch, cambios staged/unstaged, last commit. | | git_log(limit?) | limit?: number (default 10, max 1000) | [{ hash, message, author, date }] | Historial de commits. | | git_diff(target?) | target?: string (git ref, default HEAD) | { files[], patch } | Diff de cambios o contra referencia. |

Seguridad

• Argumentos seguros: usa execFileSync con arreglo de args (no shell string).
• Validación de ref: caracteres peligrosos bloqueados (null bytes, quotes, pipes, etc.).
• Max output: 10MB.

Ejemplos de output

git_status(): ``json { "branch": "main", "isClean": false, "staged": ["src/server.ts"], "unstaged": ["README.md"], "untracked": ["better-mcp.schema.json"], "ahead": 2, "behind": 0, "lastCommit": { "hash": "a1b2c3d4e5f6...", "message": "feat: add database tools", "author": "Erne Santana", "date": "2025-06-22 14:30:00 -0400" } } ``

git_log(3): ``json [ { "hash": "a1b2c3d4e5f6...", "message": "feat: add database tools", "author": "Erne Santana", "date": "2025-06-22 14:30:00 -0400" }, { "hash": "b2c3d4e5f6a7...", "message": "feat: initial shell tools", "author": "Erne Santana", "date": "2025-06-21 10:15:00 -0400" } ] ``

git_diff(): ``json { "files": ["src/server.ts", "README.md"], "patch": "diff --git a/src/server.ts b/src/server.ts\nindex abc..def 100644\n--- a/src/server.ts\n+++ b/src/server.ts\n@@ -1,3 +1,4 @@\n+// new line\n import { Server } from \"...\";" } ``

ℹ️ Project (project_*)

Siempre disponible (no requiere config específica).

| Tool | Input | Returns | Descripción | |---|---|---|---| | project_info() | — | { project, name, description, root, stack, directoryCount, fileCount, totalSizeBytes, hasConfig, enabledTools, availableCommands, resources } | Stack, estructura, configs detectados, tools habilitadas. | | read_resource(name) | name: string | { name, content, path } | Lee recurso del proyecto (handoff, plan, doc, schema). |

Ejemplos de output

project_info(): ``json { "project": "better-mcp", "name": "Better MCP Server", "description": "MCP server for AI agents", "root": "/home/user/better-mcp", "stack": ["typescript", "node"], "directoryCount": 8, "fileCount": 24, "totalSizeBytes": 48512, "hasConfig": { "node": true, "typescript": true, "docker": true, "github-actions": false }, "enabledTools": ["filesystem", "shell", "git"], "availableCommands": ["tsc", "build", "test", "lint", "deploy"], "resources": { "handoff": "/home/user/better-mcp/HANDOFF.md", "schema": "/home/user/better-mcp/prisma/schema.prisma" } } ``

read_resource("handoff"): ``json { "name": "handoff", "content": "# Project Handoff\n\nThis is the README content...", "path": "/home/user/better-mcp/HANDOFF.md" } ``

🔐 Auth (auth_*)

| Tool | Args | Descripción | Requiere auth? | |---|---|---|---| | auth_confirm(id) | confirmationId | Aprueba una operación pendiente | — | | auth_reject(id) | confirmationId | Rechaza una operación pendiente | — | | auth_status() | — | Muestra confirmaciones pendientes | — |

Modos de auth:

• auto (default): Sin confirmación — operaciones destructivas ejecutan directo
• confirm: Operaciones destructivas retornan { blocked: true, confirmationId } — debes llamar auth_confirm() para aprobar
• token: Requieres pasar confirmationToken en los args de toda operación destructiva
• interactive (HTTP only): El server envía SSE events pidiendo confirmación

Operaciones que gatillan auth:

• fs_write, fs_delete — modificación de archivos
• shell_run — comandos con palabras clave: deploy, reset, drop, delete, restart, migrate
• shell_raw — ejecución arbitraria
• db_query — SQL con DROP, ALTER, TRUNCATE, DELETE

🏗️ Workspace (workspace_*)

| Tool | Args | Descripción | |---|---|---| | workspace_list_projects() | — | Lista todos los proyectos configurados con su stack, root y tools | | workspace_set_project(name) | name | Define el proyecto activo para tools sin project explícito |

Cuando la config tiene múltiples proyectos (projects[]), todas las tools aceptan un parámetro opcional project para operar sobre un proyecto específico. Si se omite, se usa el proyecto default (el primero).

🔌 Plugins (plugin_*)

Las tools de plugins se registran como plugin_<nombre>_<tool>. Se descubren automáticamente del directorio plugins/.

Config: ``json { "tools": { "plugins": { "dir": "plugins/", "enabled": true, "allowlist": ["my-plugin"], "timeout": 30 } } } ``

Ejemplo incluido: plugins/example-echo.ts — tools echo y greet.

---

Instalación

npm / npx (recomendado)

npm install -g @erquier/better-mcp
# o, sin instalar nada:
npx @erquier/better-mcp        # arranca en stdio sobre el cwd (zero-config)

Esta es la vía sin fricción: el cliente MCP del agente arranca el binario en stdio y queda todo en local, sin red ni imágenes. fs_search cae a una búsqueda en Node si no hay ripgrep, y las DB tools solo se activan si detecta una DATABASE_URL de Postgres (y requieren psql).

Docker (opcional / avanzado)

No es necesario para el uso normal — la vía npx/stdio de arriba evita imágenes por completo. Usá Docker solo si querés exponer better-mcp como servicio HTTP compartido (atá el puerto a 127.0.0.1 y configurá auth, ya que el modo HTTP no autentica por sí solo).

docker pull ghcr.io/erquier/better-mcp
docker run -v $(pwd):/project -p 127.0.0.1:3100:3100 ghcr.io/erquier/better-mcp --http

Python — ✅ Disponible

pip install better-mcp

from better_mcp import BetterMcpClient

client = BetterMcpClient("http://localhost:3100")
info = await client.project_info()
print(info)

---

Configuración completa

El archivo better-mcp.json puede ir en la raíz del proyecto o pasarse con npx better-mcp run path/to/better-mcp.json.

Schema de validación

Un schema JSON completo está disponible para autocompletado en IDE:

• URL: https://raw.githubusercontent.com/erquier/better-mcp/main/better-mcp.schema.json
• Archivo local: better-mcp.schema.json

Agrégalo a tu config: ``json { "$schema": "https://raw.githubusercontent.com/erquier/better-mcp/main/better-mcp.schema.json" } ``

Campos de configuración

| Campo | Tipo | Requerido | Default | Descripción | |---|---|---|---|---| | project | string | ✅ | — | Identificador corto del proyecto | | root | string | ✅ | — | Ruta absoluta al proyecto | | name | string | ❌ | project | Nombre para mostrar | | description | string | ❌ | "" | Descripción breve | | stack | string[] | ❌ | [] | Tags de tecnología | | tools.fs | object | ❌ | — | Filesystem tools | | tools.fs.allowedPaths | string[] | ✅ | — | Paths absolutos permitidos | | tools.fs.maxFileSize | number | ❌ | 52428800 (50MB) | Máximo tamaño de archivo | | tools.db | object | ❌ | — | Database tools | | tools.db.url | string | ✅ | — | URL PostgreSQL (soporta ${VAR}) | | tools.db.readOnly | boolean | ❌ | true | Solo SELECT/WITH | | tools.db.schemas | string[] | ❌ | ["public"] | Schemas para db_schema | | tools.db.maxRows | number | ❌ | 500 | Límite de filas | | tools.shell | object | ❌ | — | Shell tools | | tools.shell.commands | object | ✅* | — | Map nombre → comando shell | | tools.shell.allowRaw | boolean | ❌ | false | Habilitar shell_raw | | tools.git | object | ❌ | — | Git tools | | tools.git.enabled | boolean | ❌ | true | Habilitar/deshabilitar git | | tools.git.maxCommits | number | ❌ | 50 | Máx commits en git_log | | resources | object | ❌ | {} | Recursos nombre → path |

\ Requerido si el grupo de tools está presente.*

Variables de entorno

El config soporta ${VAR_NAME} que se resuelven del entorno en tiempo de ejecución. Útil para credenciales de DB, tokens, etc.

{
  "tools": {
    "db": {
      "url": "${DATABASE_URL}"
    }
  }
}

Modos de ejecución (CLI)

# Modo automático (busca better-mcp.json en cwd)
better-mcp

# Modo stdio (default)
better-mcp run

# Modo HTTP (SSE transport)
better-mcp --http
better-mcp --http --port 8080

# Con ruta de config
better-mcp run path/to/config.json
better-mcp --config path/to/config.json
better-mcp path/to/config.json

---

Diagrama de arquitectura

┌─────────────────┐     MCP protocol     ┌──────────────────────────┐
│ Hermes Agent    │◄───────────────────►│                          │
│ Claude Code     │                      │   better-mcp server       │
│ Cursor          │                      │   (stdio transport)      │
│ Cline           │                      │                          │
│ Cualquier       │                      ├──────────────────────────┤
│ cliente MCP     │                      │                          │
└─────────────────┘                      │  Tools:                  │
                                          │  ├─ fs_read             │
┌─────────────────┐                       │  ├─ fs_write            │
│ Config          │                       │  ├─ fs_search           │
│                 │                       │  ├─ fs_list             │
│ better-mcp.json ├───────cargado────────►│  ├─ db_query            │
│ (JSON Schema)   │                       │  ├─ db_schema           │
└─────────────────┘                       │  ├─ shell_run            │
                                          │  ├─ shell_raw            │
                                          │  ├─ git_status          │
                                          │  ├─ git_log             │
                                          │  ├─ git_diff            │
                                          │  ├─ workspace_list_projects│
                                          │  ├─ workspace_set_project │
                                          │  ├─ auth_confirm          │
                                          │  ├─ auth_reject           │
                                          │  ├─ auth_status           │
                                          │  ├─ project_info          │
                                          │  ├─ read_resource         │
                                          │  └─ plugin_*              │
                                          │                          │
                                          └──────────┬───────────────┘
                                                     │
            ┌────────────────────────────────────────┼────────────────────────┐
            │           Ejecución controlada          │                        │
            ▼                                        ▼                        ▼
   ┌──────────────┐                        ┌──────────────┐        ┌──────────────┐
   │  Filesystem  │    ┌──────────────┐    │   Database   │        │     Git      │
   │  (read/write │    │ Shell (build │    │  (SQL RO)    │        │ (status/log/ │
   │   /search)   │    │  /test/lint) │    │              │        │    diff)     │
   └──────────────┘    └──────────────┘    └──────────────┘        └──────────────┘

El server corre como proceso stdio (transporte MCP estándar) y expone tools MCP estándar. Cada tool opera sobre el proyecto usando la configuración provista. No necesita permisos especiales más allá del acceso que tenga el usuario que lo ejecuta.

---

Seguridad

| Mecanismo | Descripción | |---|---| | Auth Gates | 4 modos: auto (sin gates), confirm (soft-block + confirmación), token (token en args), interactive (SSE events) | | Read-only DB | db_query solo ejecuta SELECT/WITH por defecto | | Comandos whitelist | shell_run solo ejecuta comandos definidos en config | | Raw sanitization | shell_raw bloquea backticks y newlines | | Paths restringidos | fs_* solo opera dentro de allowedPaths con validación symlink | | Null byte rejection | Todas las rutas son validadas contra null bytes | | Size limits | Max file read: 50MB, max write: 10MB, max output: 10MB | | Timeout control | Shell commands tienen timeouts configurables (max 3600s) | | Sin red | Sin conexiones externas (excepto la DB configurada) | | Input validation | Todos los inputs de usuario son validados (tipos, longitudes, caracteres) | | Sin dependencias externas | Solo el SDK MCP oficial |

Para ambientes restrictivos: deshabilitar shell.allowRaw, limitar db.schemas, o configurar git.enabled: false. Para ops destructivas, activar auth.mode: "confirm" para requerir aprobación explícita.

---

Roadmap

MVP (v0.1) — ✅ Completado

• [x] Config better-mcp.json
• [x] Server MCP base (TypeScript, SDK oficial)
• [x] fs_read, fs_write, fs_search, fs_list
• [x] shell_run con comandos configurados
• [x] git_status, git_log, git_diff
• [x] project_info, read_resource

v0.2 — ✅ Completado

• [x] db_query, db_schema
• [x] shell_raw (restringible)
• [x] Mejoras de seguridad (path validation symlink, null bytes, rate limiting input validation)
• [x] Docker image (multi-stage build)
• [x] Testing suite completa (Vitest, 129+ tests)
• [x] npm publish (@erquier/better-mcp)
• [x] JSON Schema para IDE autocomplete
• [x] CONTRIBUTING.md

v0.3 — ✅ Completado

• [x] HTTP transport (SSE) — Servidor HTTP con Node.js built-in, zero deps externas
• [x] Soporte multi-proyecto (monorepo) — projects[] en config + workspace tools
• [x] Integración CI/CD (GitHub Actions) — Matrix Node 18/20/22 + publish automático
• [x] Tests de plugins (18 tests nuevos)

v1.0 — ✅ Completado

• [x] Auth gates — 4 modos (auto, confirm, token, interactive) con soft-block
• [x] Workspace mode — workspace_list_projects + workspace_set_project
• [x] Python SDK — pip install better-mcp, cliente async con Pydantic models
• [x] Plugins personalizados — plugin discovery, allowlist, ejemplo echo/greet

---

Casos de uso

🏪 Para Cuadre POS

{
  "project": "cuadre",
  "root": "/opt/entretrespos",
  "tools": {
    "fs": { "allowedPaths": ["/opt/entretrespos"] },
    "db": { "url": "${DATABASE_URL}", "readOnly": true },
    "shell": {
      "commands": {
        "tsc": "npx tsc --noEmit",
        "build": "docker compose build app",
        "test:e2e": "pnpm test:e2e",
        "migrate-status": "pnpm prisma migrate status",
        "deploy": "git pull --ff-only && docker compose build app && docker compose run --rm -T --no-deps app pnpm prisma migrate deploy < /dev/null && docker compose up -d"
      }
    }
  },
  "resources": {
    "handoff": "CUADRE-HANDOFF.md"
  }
}

🏗️ Para cualquier proyecto

• Web app (Next.js, React, Vue, Angular)
• API (Express, FastAPI, Django)
• Scripts y herramientas CLI
• Proyectos con Docker Compose
• Monorepos

---

Desarrollo

git clone https://github.com/erquier/better-mcp
cd better-mcp
pnpm install
pnpm dev           # Desarrollo con watch (tsc --watch)
pnpm build         # Producción
pnpm test          # Tests (Vitest)
npx tsc --noEmit   # Type-check solo

Prerrequisitos

• Node.js 18+
• pnpm (corepack enable)
• ripgrep (rg) — necesario para fs_search y sus tests
• PostgreSQL client (psql) — necesario para DB tools

Stack técnico

• TypeScript (strict mode, ES2022)
• @modelcontextprotocol/sdk ^1.0.0
• Vitest para testing
• Docker (multi-stage build, opcional)
• pnpm como package manager

---

Preguntas frecuentes

¿Por qué no usar los MCP servers oficiales por separado? Porque son piezas independientes que requieren configurar N servidores diferentes. better-mcp los unifica en uno solo con una config compartida y herramientas pensadas para el flujo completo de desarrollo.

¿Qué lo hace "better"?

• Un solo comando para instalar y ejecutar
• Config por proyecto en un JSON con schema de validación
• Tools pensadas para el flujo real de desarrollo (no solo CRUD de archivos)
• Escapado correcto de código (no más heredocs rotos)
• Agnóstico al agente (cualquier cliente MCP funciona)

¿Y si mi proyecto no tiene DB o no usa Git? Las tools se habilitan según la config. Si no configuras db, no se exponen tools de DB. Si deshabilitas git, no se exponen tools de git.

¿Es seguro? Sí. Cada tool opera bajo las restricciones de la config: paths permitidos, DB read-only, comandos whitelist, inputs validados. Y el server corre localmente con los permisos del usuario que lo ejecuta.

¿Necesito cambiar mi proyecto para usarlo? No. Solo agregar un better-mcp.json a la raíz. El resto es configuración de tu cliente MCP.

¿Qué es MCP? El Model Context Protocol es un protocolo abierto que permite a agentes de IA interactuar con herramientas y recursos externos de manera estructurada.

---

Licencia

MIT © Erne Santana

---

Links

• GitHub
• JSON Schema
• MCP Protocol
• Reportar un issue