Is Better Mcp safe to install?

SaferSkills independently audited Better Mcp (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.

CategoryWeightCategory scoreContribution

Securityprompt, exec, net, exfil, eval

35%

100

35.0 pts

Supply chainhash, typosquat, maintainer, lockfile

20%

100

20.0 pts

Maintenancestaleness, pinning, CI

15%

100

15.0 pts

TransparencySKILL.md, perms, README

15%

100

15.0 pts

Communityinstalls, verify, response

15%

100

15.0 pts

Findings & checks · 0 flagged

Securityscore 100 · 0 findings

✓—All security checks passedNo findings in this category for the latest scan.pass

Supply chainscore 100 · 0 findings

✓—All supply chain checks passedNo findings in this category for the latest scan.pass

Maintenancescore 100 · 0 findings

✓—All maintenance checks passedNo findings in this category for the latest scan.pass

Transparencyscore 100 · 0 findings

✓—All transparency checks passedNo findings in this category for the latest scan.pass

Communityscore 100 · 0 findings

✓—All community checks passedNo findings in this category for the latest scan.pass

The primary manifest — the file an agent reads to learn what this artifact does.

README.md · 1 file

README.md28.1 KB · Markdown

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):

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):

{
  "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)`:

{
  "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")`:

{
  "path": "/tmp/better-mcp/test.txt",
  "bytesWritten": 11
}

*`fs_search("import", ".ts")`**:

{
  "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(".")`:

[
  { "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")`:

{
  "columns": ["id", "name", "email"],
  "rows": [
    { "id": "1", "name": "Alice", "email": "[email protected]" },
    { "id": "2", "name": "Bob", "email": "[email protected]" },
    { "id": "3", "name": "Charlie", "email": "[email protected]" }
  ],
  "rowCount": 3,
  "truncated": false
}

`db_schema()`:

{
  "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'"):

{
  "stdout": "tests ok",
  "stderr": "",
  "exitCode": 0,
  "duration": 45
}

`shell_run("fail")` (con config "fail": "exit 1"):

{
  "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()`:

{
  "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)`:

[
  {
    "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()`:

{
  "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()`:

{
  "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")`:

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

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

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

Is Better Mcp safe to install?

better-mcp 🚀

¿Por qué better-mcp?

¿Qué problema resuelve?

Quick Start

1. Instalar

2. (Opcional) Generar better-mcp.json

3. Conectarlo desde cualquier cliente MCP

4. Usar las tools desde cualquier agente

Tools disponibles — API completa

📁 Filesystem (fs_*)

🗄️ Database (db_*)

🖥️ Shell (shell_*)

🔗 Git (git_*)

ℹ️ Project (project_*)

🔐 Auth (auth_*)

🏗️ Workspace (workspace_*)

🔌 Plugins (plugin_*)

Instalación

npm / npx (recomendado)

Docker (opcional / avanzado)

Python — ✅ Disponible

Configuración completa

Schema de validación

Campos de configuración

Variables de entorno

Modos de ejecución (CLI)

Diagrama de arquitectura

Seguridad

Roadmap

MVP (v0.1) — ✅ Completado

v0.2 — ✅ Completado

v0.3 — ✅ Completado

v1.0 — ✅ Completado

Casos de uso

🏪 Para Cuadre POS

🏗️ Para cualquier proyecto

Desarrollo

Prerrequisitos

Stack técnico

Preguntas frecuentes

Licencia

Links

Audit the pieces. Scan the whole. Decide.

2. (Opcional) Generar `better-mcp.json`

📁 Filesystem (`fs_*`)

🗄️ Database (`db_*`)

🖥️ Shell (`shell_*`)

🔗 Git (`git_*`)

ℹ️ Project (`project_*`)

🔐 Auth (`auth_*`)

🏗️ Workspace (`workspace_*`)

🔌 Plugins (`plugin_*`)