Skip to main content
Glama
infra-mcp-template

infra-mcp-template

by aimuzov

Starting point of an aimuzov MCP server on infra-mcp-kit: a stdio server with one example tool, a hosted connector with OAuth and pages in the "Signal" style, checks, release and deploy. The examples below create example-mcp.

What's inside

  • src/server.ts: the server and its tools. The echo example reads API_TOKEN in stdio and the token from the sign-in form in the connector.

  • src/http.ts: the connector: tokenFormLogin, OAuth in sqliteStore, the GET /api/status route.

  • src/frontend: the service's own pages on the kit layout. status.astro with a Svelte island shows the pattern.

  • astro.config.mjs: mcpPages() with the landing, sign-in, error and 404 pages.

  • deploy/: the image and the compose file for the projects server behind the shared Caddy.

  • .github/workflows: check on every PR, release with npm publishing and deploy, pr-meta, Renovate.

Related MCP server: MCP-Server-Starter-Kit

New server

  1. Create the repository from the template and replace the placeholders. The READMEs stay out of the replacement: a new server writes its own.

    gh repo create aimuzov/example-mcp --public --template aimuzov/infra-mcp-template --clone
    cd example-mcp
    grep -rl --exclude-dir=node_modules --exclude-dir=.git --exclude='README*' \
        -e __NAME__ -e __DOMAIN__ -e __DESCRIPTION__ . |
        xargs perl -pi -e 's/__NAME__/example-mcp/g; s/__DOMAIN__/example-mcp.aimuzov.online/g; s/__DESCRIPTION__/What the server does, in one line/g'
    npm install
  2. Reset the version and the changelog inherited from the template:

    echo '{}' > .release-please-manifest.json
    npm pkg set version=0.0.0
    : > CHANGELOG.md
  3. Replace echo in src/server.ts with real tools and update the list in src/server.test.ts.

  4. Implement verifyToken in src/http.ts: check the token with the service API and return { subject: <user id>, claims: { apiToken: token } }. The claims reach createServer in auth.extra, so the tools get the token. Until then the connector refuses every sign-in.

  5. Write the texts of the pages in mcpPages in astro.config.mjs: tagline, lead, tools, the sign-in form. Keep or drop /status.

  6. In Settings → Actions → General turn on "Allow GitHub Actions to create and approve pull requests": release-please opens the release PR with it.

A stdio-only server drops the connector: src/http.ts, src/http.test.ts, http in src/index.ts, astro.config.mjs, svelte.config.js, postcss.config.mjs, src/frontend, deploy/, the Astro and site-kit dev dependencies and docker in check.yml.

Run locally

npm start                                  # stdio, what a client starts
npm run build && node build/index.js serve --http
npm run dev:pages                          # the pages alone, with Astro HMR

serve --http reads the environment, see .env.example: PUBLIC_URL=http://localhost:8080 and an AUTH_SECRET of 32 characters or more (openssl rand -base64 48) are enough locally. The data, auth.db included, goes to <NAME>_DATA_DIR, $XDG_CONFIG_HOME/<name> or ~/.config/<name>. LOG_LEVEL=debug prints stacks.

Placeholders

  • __NAME__: the repository, the npm package @aimuzov/__NAME__, the binary, the container and its volume, the title of /status.

  • __DOMAIN__: the address of the hosted connector, in .env.example and in the deploy of release.yml.

  • __DESCRIPTION__: one line for package.json and the landing page.

Release and deploy

A merge into main only updates the release PR of release-please. Merging that PR cuts a release, the checks run again, and then:

  • with the repository variable NPM_PUBLISH=true and the secret NPM_TOKEN the release goes to npm; the token has to bypass 2FA, or npm asks for a one-time password;

  • with DEPLOY_ENABLED=true and the secret DEPLOY_SSH_KEY it goes to the projects server.

A manual run of release publishes the tag given in tag; deploy takes the tag too, or the newest main when it is empty.

The projects server needs the steps of Adding a project in infra-server once: a deploy key, the clone in /srv/example-mcp, its .env from .env.example, sites/example-mcp.caddy with reverse_proxy example-mcp:8080 and the domain pointed at the server. The container listens on 8080, keeps its data in the example-mcp-data volume and joins the edge network of Caddy without published ports.

Production containers have explicit RAM and total RAM-plus-swap limits. CI validates every service against the shared infra-server policy at https://github.com/aimuzov/infra-server/blob/main/docs/resource-limits.md. Choose any increased budget from measured peaks and keep the Node heap below the container limit.

Available Tools

1 tool
echoEchoB

Return the message back. An example tool of the template.

Inputs: message (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 1 tool

    Disambiguation5/5

    There is only one tool, so there is no risk of confusing it with another tool. Its purpose as a template echo example is clear.

    Naming Consistency4/5

    The single tool name 'echo' is simple and readable. However, with only one tool there is no meaningful naming pattern to evaluate.

    Tool Count2/5

    A single trivial example tool is far too thin for a server named infra-mcp-template. It does not provide a useful infrastructure tool surface.

    Completeness1/5

    The surface contains only an echo example and no actual infrastructure operations. There is no CRUD or lifecycle coverage for any relevant domain.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables developers to scaffold secure-by-default MCP servers with deny-all permissions, typed tool stubs, and pre-wired audit hooks, while enforcing security posture through CI.
      7 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables developers to scaffold production-ready MCP servers with typed tools, resources, prompts, transports, authentication, and database integrations.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables developers to scaffold and deploy authenticated MCP servers with persona-scoped encrypted external connections, configuration routes, and MCP Apps UI support.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides a ready-to-run stdio server scaffold that agents can launch via npx without installing anything, bundled into a single file with an example tool, strict tool-schema checks, tests, and bilingual documentation. It gives developers a consistent foundation for building, validating, and shipping new MCP servers that agent-kit can execute directly.
      1
      MIT