mcp-dev-core

mcp-dev-core es un servidor MCP local, modular y orientado a productividad de desarrollo. Su foco no es exponer una shell universal, sino un conjunto de capacidades seguras, tipadas y auditables para leer contexto, operar sobre Git, ejecutar validaciones controladas y aplicar cambios sensibles con flujo de proposal y approval.

CI: GitHub Actions ejecuta typecheck, lint, test y build en pushes y pull requests sobre main.

Por que existe

Muchos MCP locales empiezan como un conjunto de comandos rapidos y terminan mezclando lectura, escritura y ejecucion arbitraria sin una politica clara. mcp-dev-core existe para empujar el diseño en la direccion contraria:

• tools especificas en vez de comandos universales
• seguridad declarativa por tool
• execution modes globales
• proposal flow para operaciones sensibles
• stores explicitos de contexto en memoria
• persistencia local opcional para sessions, artifacts y proposals

Estado actual

El proyecto ya incluye una base funcional y varias capacidades utiles para flujos reales de desarrollo, pero sigue en etapa temprana. La persistencia externa, el modelo multiusuario, las aprobaciones remotas y el sandbox fuerte de procesos no forman parte de la version actual.

Stack

• Node.js
• TypeScript
• @modelcontextprotocol/sdk
• Zod
• Vitest
• ESLint

Features principales

• Servidor MCP por stdio
• workspaceRoot seguro y bloqueo de path traversal
• contrato formal de tools con input/output validados
• SecurityGate central con safe, normal y trusted
• auditoria estructurada por invocacion
• tools de lectura de proyecto y codebase
• tools Git read-only y Git write especificas
• ejecucion controlada de tests y linter sin shell arbitrario
• write_file_patch con flujo preview -> approve -> apply
• stores en memoria para proposals, artifacts y sessions

Arquitectura resumida

src/
├── context/    # Stores explicitos de artifacts y sessions
├── schemas/    # Config, inputs y outputs Zod
├── security/   # Policies, gate, proposals y auditoria
├── server/     # Composicion, config, logger y arranque
├── services/   # Filesystem, git, procesos y deteccion de proyecto
├── tools/      # Definiciones MCP, pipeline y handlers
├── types/      # Tipos compartidos
└── utils/      # Errores y utilidades pequenas

Configuracion

Variables soportadas:

• MCP_SERVER_NAME
• MCP_SERVER_VERSION
• LOG_LEVEL
• MCP_EXECUTION_MODE
• MCP_WORKSPACE_ROOT
• MCP_PERSISTENCE_ENABLED
• MCP_STATE_DIR
• MCP_MAX_READ_FILE_BYTES
• MCP_MAX_READ_MULTIPLE_FILES
• MCP_MAX_READ_MULTIPLE_FILES_TOTAL_BYTES
• MCP_PROCESS_TIMEOUT_MS
• MCP_PROCESS_MAX_STDOUT_BYTES
• MCP_PROCESS_MAX_STDERR_BYTES
• MCP_PROPOSAL_TTL_MS
• MCP_SEARCH_MAX_RESULTS
• MCP_SEARCH_MAX_FILE_BYTES
• MCP_OVERVIEW_MAX_ENTRIES
• MCP_LIST_DIRECTORY_MAX_ENTRIES

Ejemplo:

cp .env.example .env

MCP_EXECUTION_MODE=safe
MCP_WORKSPACE_ROOT=/home/tu-usuario/proyecto
MCP_PERSISTENCE_ENABLED=true
MCP_STATE_DIR=.mcp-dev-core/state
MCP_PROPOSAL_TTL_MS=900000

Notas sobre persistencia:

• Si MCP_PERSISTENCE_ENABLED=false, los stores siguen funcionando solo en memoria.
• Si MCP_PERSISTENCE_ENABLED=true, el servidor carga snapshots JSON al iniciar y guarda cambios al mutar sessions, artifacts y proposals.
• MCP_STATE_DIR se resuelve localmente y se usa solo para estado simple del proceso; no es una base de datos ni un mecanismo de sync.

Execution modes

• safe: lectura y contexto de bajo riesgo. Bloquea escritura, procesos y git write.
• normal: habilita operaciones moderadas como run_tests, run_linter, save_artifact, create_session y create_branch.
• trusted: habilita operaciones sensibles que requieren policy mas estricta y, cuando aplica, proposals aprobadas.

Seguridad

Reglas de diseño actuales:

• no existe run_command
• no existe write_file libre
• no existe git arbitrario
• toda operacion sensible se modela como capacidad especifica

Protecciones actuales:

• workspaceRoot restringido
• bloqueo de traversal y escapes fuera del workspace
• SecurityGate central antes de cada handler
• metadata de seguridad por tool
• auditoria estructurada
• proposals explicitas para cambios sensibles
• stores de contexto y sesion explicitos, no memoria magica
• persistencia JSON local opcional restringida al stateDir configurado

Capabilities actuales:

• read_files
• search_code
• context_read
• context_write
• git_read
• git_write
• process_run
• proposal_approve
• write_files

Tools destacadas

Lectura y contexto:

• read_project_overview
• read_file
• read_multiple_files
• search_codebase
• list_directory

Git read-only:

• git_status
• git_diff_summary
• generate_commit_message_preview

Observabilidad y administracion read-only:

• read_system_status
• list_recent_audit_events
• list_pending_proposals
• read_state_snapshot
• read_metrics_summary
• list_recent_traces

Git write especifico:

• create_branch
• commit_changes

Procesos controlados:

• run_tests
• run_linter

Cambios de archivos:

• write_file_patch
• approve_proposal

Contexto operativo:

• save_artifact
• list_artifacts
• read_artifact
• create_session
• list_sessions
• read_session
• set_active_session

Estas tools administrativas son solo de inspeccion. No existen operaciones administrativas destructivas en la version actual.

Metricas y trazas actuales:

• metricas acumuladas por tool y por outcome
• duracion total y promedio por tool
• trazas recientes en memoria con traceId, outcome, executionMode y referencias opcionales a sessionId y proposalId
• todo es local, ligero y sin exportadores externos

Flujo de proposals

Las operaciones sensibles no inventan una aprobacion separada por dominio. Se reutiliza el mismo flujo:

1. dryRun genera preview o proposal
2. approve_proposal aprueba la proposal
3. la tool sensible aplica el cambio real con proposalId

Actualmente este flujo se usa para:

• write_file_patch
• commit_changes

Ejemplos rapidos

Crear una rama:

{
  "branchName": "feature/git-workflow",
  "checkout": true
}

Generar preview de commit:

{}

Proponer un commit:

{
  "commitMessage": "chore(git): add commit workflow tools",
  "dryRun": true
}

Crear una sesion:

{
  "title": "Refactor auth flow",
  "goal": "Separar handlers y servicios",
  "setActive": true
}

Guardar un artifact:

{
  "kind": "note",
  "title": "Current plan",
  "content": "Implement artifact store and tools",
  "sessionId": "11111111-1111-1111-1111-111111111111"
}

Leer una sesion:

{
  "sessionId": "11111111-1111-1111-1111-111111111111"
}

Cambiar la sesion activa:

{
  "sessionId": "11111111-1111-1111-1111-111111111111"
}

Leer un artifact:

{
  "artifactId": "22222222-2222-2222-2222-222222222222"
}

Aprobar una proposal:

{
  "proposalId": "33333333-3333-3333-3333-333333333333"
}

Aplicar write_file_patch:

{
  "path": "src/index.ts",
  "findText": "before",
  "replaceWith": "after",
  "proposalId": "33333333-3333-3333-3333-333333333333",
  "dryRun": false
}

Compatibilidad de cliente:

• las tools realmente sin input aceptan tanto llamada sin arguments como arguments: {}
• las tools con argumentos requeridos siguen validando strings, arrays y UUIDs de forma estricta

Desarrollo

npm install
cp .env.example .env
npm run dev

Validacion

npm run typecheck
npm run lint
npm run test
npm run build
npm run start

Smoke MCP

Los smoke tests MCP levantan el servidor real por stdio, conectan un cliente MCP del SDK y ejecutan una bateria minima contra un workspace temporal aislado. No dependen del MCP Inspector UI ni modifican este repositorio.

npm run smoke:mcp
npm run smoke:mcp:safe
npm run smoke:mcp:normal
npm run smoke:mcp:trusted

Cobertura actual:

• safe: lectura de proyecto y archivos, search_codebase, read_multiple_files, estado Git read-only, observabilidad read-only y snapshots administrativos.
• normal: sesiones, artifacts, run_linter, run_tests, create_branch y bloqueos esperados para operaciones sensibles.
• trusted: proposals de write_file_patch y commit_changes, approve_proposal, listado de proposals pendientes y bloqueos por approval cuando corresponde.

Pruebas negativas incluidas:

• bloqueo en safe para run_tests, run_linter, create_branch, save_artifact y write_file_patch apply.
• bloqueo en normal para commit_changes apply y write_file_patch apply.
• bloqueo en trusted para commit_changes apply cuando la proposal sigue pendiente.

Salida esperada:

== Mode safe ==
[PASS] tools/list incluye el set minimo
[PASS] health_check responde
...
Summary safe: 7 passed, 0 failed

== Mode normal ==
[PASS] create_session responde
...
Summary normal: 11 passed, 0 failed

CI

El workflow ci.yml ejecuta en GitHub Actions:

• npm ci
• npm run typecheck
• npm run lint
• npm run test
• npm run build

Contribuir

Lee primero CONTRIBUTING.md y SECURITY.md.

En resumen:

• mantener tools especificas, no universales
• cubrir cambios relevantes con tests
• respetar execution modes, SecurityGate y proposal flow
• no introducir capacidades peligrosas sin modelado explicito

Roadmap corto

• persistencia opcional para proposals, artifacts y sessions
• tools Git adicionales como revert preview o branch summary
• aprobacion interactiva mas rica
• observabilidad y reportes de auditoria mas detallados
• empaquetado y publicacion open-source mas formal