Skip to main content
Glama
Maurichilean3d

MCP Starter Kit

MCP Starter Kit

Plantilla para construir tu propio servidor MCP (Model Context Protocol) en TypeScript y conectarlo a opencode (o Claude Desktop, Cursor, etc.).

Con un MCP, un modelo de IA puede usar herramientas que tú defines: abrir una app de tu computador, leer tus notas, llamar a una API, controlar música… lo que se te ocurra.

⚡ Empezar (Windows y Mac, sin escribir comandos complicados)

Opción recomendada: pegar UNA línea en la terminal

Descarga e instala todo sin que Windows ni macOS muestren alertas de "archivo peligroso" (esas alertas solo aparecen en archivos bajados con el navegador).

Windows — abre PowerShell (menú Inicio → escribe PowerShell) y pega:

irm https://raw.githubusercontent.com/Maurichilean3d/mcp-starter-kit/main/install.ps1 | iex

Mac (Apple Silicon o Intel) — abre Terminal (Cmd+Espacio → Terminal) y pega:

curl -fsSL https://raw.githubusercontent.com/Maurichilean3d/mcp-starter-kit/main/install.sh | bash

Esto copia el kit a tu carpeta de usuario (mcp-starter-kit) y abre el instalador. Es seguro revisar antes lo que hace: son los archivos install.ps1 / install.sh de este mismo repositorio.

Opción alternativa: descargar el ZIP

  1. En esta página pulsa el botón verde Code → Download ZIP y descomprímelo (en Windows: clic derecho → Extraer todo...; no lo ejecutes desde dentro del .zip).

  2. Haz doble clic en el archivo de entrada:

Windows

macOS

Iniciar.bat

Iniciar.command

Como el ZIP viene del navegador, el sistema puede mostrar un aviso la primera vez:

  • Windows: "Windows protegió su PC" → Más información → Ejecutar de todas formas.

  • Mac: "…podría ser peligroso" o "no se puede abrir". Abre Terminal y pega (cambia la ruta si lo descomprimiste en otro sitio):

    xattr -dr com.apple.quarantine ~/Downloads/mcp-starter-kit-main
    bash ~/Downloads/mcp-starter-kit-main/Iniciar.command

    Con bash … también se evita el error "permiso denegado" del ZIP de GitHub. La alerta desaparece del todo solo si el archivo está firmado con una cuenta de desarrollador de Apple de pago, que este proyecto no tiene.

Qué hace

El programa te va preguntando [S/N] antes de instalar lo que falte (Node.js, opencode, Antigravity), prepara el MCP y abre un menú:

  1. Crear un MCP para una app de tu equipo (Constructor automático)

  2. Abrir opencode con el MCP del kit

  3. Abrir Antigravity con el MCP del kit

  4. Diagnóstico (si algo falla: crea diagnostico.txt para enviarlo a quien te ayuda)

La primera vez tarda un par de minutos; después abre al instante.

¿Prefieres git? git clone https://github.com/Maurichilean3d/mcp-starter-kit.git y luego el mismo archivo de entrada (con git tampoco aparecen alertas).

Más detalle y solución de problemas: docs/00-instalacion-windows-mac.md y docs/06-depuracion.md. El constructor automático (con sus advertencias de seguridad): docs/07-constructor-automatico.md.

Related MCP server: Example MCP Server

Inicio rápido con la terminal (cualquier sistema)

Requisitos: Node.js 18+ y opencode.

git clone https://github.com/TU-USUARIO/mcp-starter-kit.git mi-mcp
cd mi-mcp
npm install
npm run build
npm test            # debe terminar con "Prueba de humo superada."

Luego abre opencode en esta misma carpeta (opencode). El archivo opencode.json ya registra el MCP. Pregúntale:

"Usa la herramienta saludar para saludar a Ana"
"Lista mis aplicaciones instaladas y abre la calculadora"

Qué incluye

install.ps1 / install.sh        Instalacion por una linea de terminal (sin alertas del sistema)
Iniciar.bat / Iniciar.command   Punto de entrada unico (Windows / Mac): instala lo que falte y abre el menu
instalador/             Programa que hace la instalacion y el menu (setup.mjs) + generador de instaladores
constructor/            App web local que hace que opencode construya un MCP por ti
src/
  index.ts              Arranque del servidor (carga src/tools/ automáticamente)
  tools/
    ejemplo.ts          Herramientas mínimas: hora_actual, saludar
    aplicaciones.ts     Ejemplo real: listar y abrir apps (macOS/Windows/Linux)
  lib/
    exec.ts             Ejecutar programas de forma segura
    respuestas.ts       Helpers: texto(), json(), error()
templates/
  tool.template.ts      Plantilla de herramienta nueva
  PROMPT_PARA_OPENCODE.md   Prompt listo para que opencode construya tu MCP
scripts/
  new-tool.mjs          Generador de herramientas
  smoke-test.mjs        Prueba automática
  configurar-opencode.mjs   Registra el MCP en opencode con ruta absoluta
  asegurar-clis.mjs     Detecta/instala opencode y Antigravity (pide permiso)
  diagnostico.mjs       Revisa Node, npm, opencode, internet... y crea diagnostico.txt
  lanzar.mjs            Abre opencode o Antigravity con el MCP
docs/                   Guías paso a paso (léelas en orden)
AGENTS.md               Reglas que opencode lee automáticamente
opencode.json           Registro del MCP en opencode

Crear tu propio MCP

Camino A — a mano

npm run new-tool -- crear_nota     # crea src/tools/crear_nota.ts
# edita el archivo, luego:
npm run build

Reinicia opencode y tu herramienta aparece sola. No hay que registrar nada.

Camino B — con ayuda de opencode (recomendado para apps)

Abre templates/PROMPT_PARA_OPENCODE.md, elige la app de tu computador, completa el prompt y pégalo en opencode. Gracias a AGENTS.md, opencode ya conoce las reglas del proyecto.

Guías

  1. Instalación y primer uso (Windows y macOS)

  2. Conceptos: qué es MCP

  3. Tu primer MCP paso a paso

  4. Conectar con opencode (y otros clientes)

  5. Construir un MCP para una aplicación

  6. Seguridad y buenas prácticas

  7. Depuración y problemas comunes

  8. Constructor automático: opencode escribe el MCP por ti

Comandos

Comando

Qué hace

npm run setup

Instala lo que falte y abre el menú (igual que Iniciar)

npm run crear-mcp

Abre el Constructor automático de MCP

npm run build

Compila TypeScript a dist/

npm test

Compila y verifica que el servidor responde

npm run inspect

Abre el MCP Inspector (interfaz visual para probar herramientas)

npm run new-tool -- nombre

Crea una herramienta nueva

npm run configurar

Registra el MCP en opencode (ruta absoluta)

npm run configurar:global

Lo registra para todas las carpetas

npm run dev

Ejecuta el servidor directo desde TypeScript

Licencia

MIT

Available Tools

4 tools
abrir_aplicacionAbrir aplicacionA

Abre una aplicacion instalada por su nombre (ej: 'Safari', 'Notepad', 'firefox'). Opcionalmente abre un archivo con ella.

NameRequiredDescriptionDefault
nombreYesNombre de la aplicacion
archivoNoRuta de un archivo a abrir con la app (opcional)

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=false, consistent with launching a process, so the description does not contradict anything. It adds the constraint that the app must be installed, but says nothing about whether the call blocks until the app opens, what happens if the path or name is invalid, or what a successful response looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the primary action, then the optional file behavior. The examples earn their place by illustrating the expected name format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter launcher with annotations covering the safety profile and no output schema, the description covers purpose and the optional file path adequately. The only real gap is error/edge-case behavior, which is minor for a tool this small.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both 'nombre' and 'archivo' are already documented in the schema. The description reinforces that the name is the app name and the file is optional, but adds no syntax, path-format, or fallback details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: 'Abre una aplicacion instalada por su nombre', with examples ('Safari', 'Notepad', 'firefox') that pin down the naming convention. It does not explicitly distinguish itself from the sibling listar_aplicaciones, but the action is specific enough to tell apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case (launch an already-installed app, optionally with a file), but there is no explicit when-not guidance, no mention of what to do when the app name is unknown (e.g., use listar_aplicaciones first), and no note on failure behavior.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hora_actualHora actualA
Read-only

Devuelve la fecha y hora actual del computador del usuario.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already tells the agent this is a safe read. The description adds genuine context beyond that: the time comes from the user's own computer, not a server or a normalized timezone, which is a meaningful behavioral distinction for an agent reasoning about timestamps. It does not state the output format or timezone, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. The verb and the returned value come first, and the qualifier about the source machine is the only added detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, no-output-schema tool, the description covers what the tool returns and where the value comes from. The only missing piece is the return format (string format, timezone/locale), which an agent might want but is not strictly required to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is empty and consistent with the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Devuelve') and a specific resource ('la fecha y hora actual del computador del usuario'), and even qualifies the source clock. It is trivially distinguishable from siblings like listar_aplicaciones or abrir_aplicacion, which operate on applications rather than returning time.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives, but for a zero-parameter utility tool the intended use (fetch the current timestamp) is self-evident from the description. Usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listar_aplicacionesListar aplicacionesA
Read-only

Lista las aplicaciones instaladas en el computador del usuario. Usala antes de abrir una app si no conoces su nombre exacto.

NameRequiredDescriptionDefault
filtroNoTexto opcional para filtrar por nombre

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true is consistent with a listing operation, and the description adds useful scope (it reads the user's own machine, not a remote registry). However, it says nothing about cost or latency of enumerating installed apps, what happens when the list is empty, or whether results are cached — the kind of context that matters for a machine-scanning tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero filler: the first states what it does, the second states when to use it. Front-loaded and every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-param read-only tool with full schema coverage and no output schema, this covers what and when adequately. The minor gap is that the return shape (bare names? paths? display names?) is never hinted at, which matters slightly for deciding whether filtro's output feeds directly into abrir_aplicacion.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'filtro' is fully documented in the schema (100% coverage) including that it matches by name and is optional. The description adds no semantics about matching behavior (substring vs exact, case sensitivity), so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ("Lista") plus specific resource ("las aplicaciones instaladas en el computador del usuario"), which an agent can immediately distinguish from abrir_aplicacion or saludar. Scope is stated, not implied.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Usala antes de abrir una app si no conoces su nombre exacto" gives a concrete trigger condition and implicitly routes the agent away from abrir_aplicacion when the app name is unknown. It stops short of naming the sibling tool explicitly or stating when not to call it (e.g. when the name is already known), so it falls just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

saludarSaludarA
Read-only

Saluda a una persona por su nombre. Util para probar que el MCP funciona.

NameRequiredDescriptionDefault
idiomaNoIdioma del saludoes
nombreYesNombre de la persona a saludar

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true is consistent with a greeting (no mutation), and the description adds nothing that contradicts it. Beyond that, it discloses almost no behavioral context (return format, language handling) — acceptable only because the operation is trivial and annotations already cover safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the core action front-loaded and the testing hint second. Nothing is wasted, though the second sentence is meta-commentary rather than operational guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a trivial two-parameter read-only greeting with a fully described schema and no output schema, the description is sufficient to call it correctly. Only the language parameter's behavior is left entirely to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters (nombre, idioma with an enum) are fully documented in the schema. The description mentions greeting by name but says nothing about the idioma parameter, so it adds no meaning beyond the schema — baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: greet a person by their name. It is clearly distinguishable from the sibling tools, which list apps, open apps, and report time, but it doesn't explicitly name them as alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Útil para probar que el MCP funciona" gives an implied usage context (testing/health check), but there are no explicit when-to-use or when-not-to-use rules, and no reference to any sibling tool as an alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.1.0
    • First observedabrir_aplicacion
    • First observedhora_actual
    • First observedlistar_aplicaciones
    • First observedsaludar

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: listing apps, opening apps, getting the current time, and greeting a person. There is no meaningful overlap that would cause an agent to misselect a tool.

Naming Consistency4/5

Tool names are consistently snake_case and mostly follow a verb_noun pattern. However, 'hora_actual' is noun_adjective and 'saludar' is a bare verb, which are minor deviations from the dominant naming style.

Tool Count5/5

Four tools is a well-scoped size for a starter kit, with each tool serving a simple, clear purpose. Nothing feels excessive or missing for the stated demo-oriented scope.

Completeness3/5

For desktop app interaction, the set covers listing and opening apps but lacks an obvious close/quit operation or app-state inspection. The time and greeting tools are useful starter utilities but do not fill that lifecycle gap.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    D
    quality
    D
    maintenance
    A foundation for building custom local Model Context Protocol (MCP) servers that provide tools accessible to AI assistants like Cursor or Claude Desktop.
    1
    37
    MIT
  • A
    license
    C
    quality
    C
    maintenance
    A minimal Node.js Model Context Protocol server that exposes two simple tools ('add' and 'getTime') that can be called from AI assistants like Claude Desktop or Cursor.
    2
    103 npm
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    A Node.js and TypeScript implementation that provides system information and health check tools for Claude Desktop. It serves as a boilerplate for building and integrating custom tools using the Model Context Protocol.
    6 npm
    ISC
  • A
    license
    Not graded
    quality
    D
    maintenance
    A local Model Context Protocol (MCP) server that exposes custom tools to Claude Desktop, enabling direct interaction with your local environment. It provides a framework for building and integrating custom TypeScript tools into the Claude interface.
    1 npm
    MIT