mcp-typescript-starter
This MCP server exposes a single echo tool over stdio or streamable HTTP.
Invoke the
echotool with a requiredmessage(1–10,000 characters) and optionalmetadataobject (up to 20 entries; keys ≤64 chars, values ≤1024 chars).Get back the same
messageandmetadataas both human-readable text content and typed structured content.Connect MCP clients through stdio (
node dist/main.js --transport stdio) or Streamable HTTP athttp://<host>:3000/mcp.Check HTTP health at
http://<host>:3000/healthzwhen usingstreamable-http.Configure transport, bind host/port, and host allowlist via
MCP_TRANSPORT,MCP_HOST,MCP_PORT, andMCP_ALLOWED_HOSTS.Run it locally, as npm artifact, or as hardened Docker container with graceful shutdown and non-root read-only support.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-typescript-starter Echo 'Hello from the MCP client' back to me."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP TypeScript Starter
MCP TypeScript Starter is a production-conscious foundation for building a Model Context Protocol server with TypeScript. It includes one typed example tool, stdio and Streamable HTTP transports, strict validation, tests, a hardened container, npm artifact verification, automated GHCR publication, and opt-in npm/MCP Registry releases.
Clone it, replace the example domain, and keep the infrastructure that real MCP servers need.
Navigation
Related MCP server: mcp-server-http-streamable
Use this starter
Click Use this template on GitHub to create a new MCP server with an independent Git history. After creating it, replace the example tool and update the project identity by following Customizing the starter.
Fork this repository when you want to contribute improvements back through a pull request. See Contributing before submitting changes.
If this starter helped you, consider giving the repository a star. It helps other TypeScript developers discover the project.
About
The starter demonstrates the complete path from a validated MCP tool definition to a client-visible structured result. The server uses the current modular MCP TypeScript SDK and Hono's Web-standard HTTP model rather than a custom server framework.
The default stdio transport is intended for local clients that launch the server as a child process. Streamable HTTP is stateless and creates a fresh MCP server for each request, so it can be replicated without shared session storage.
The example performs bounded in-memory work. There is no telemetry, application database, persistent storage, authentication, or external service dependency.
Features
Registers tools with strict Zod input and output schemas.
Demonstrates server instructions and descriptions for every tool input and output.
Returns both human-readable content and typed structured content.
Includes accurate MCP safety annotations.
Supports stdio and stateless Streamable HTTP.
Uses Hono with Host and Origin validation against DNS rebinding.
Binds HTTP to loopback by default and requires an allowlist for other interfaces.
Limits tool inputs and HTTP request bodies.
Keeps stdout exclusive to MCP protocol messages in stdio mode.
Handles SIGINT and SIGTERM with idempotent graceful shutdown.
Runs as a non-root container with read-only-root-filesystem support.
Tests configuration, stdio wiring, MCP behavior, Hono routes, and real HTTP traffic.
Packs, installs, and starts the npm artifact in CI before it can be published.
Publishes multi-architecture images only after quality checks pass.
Provides an opt-in, resumable release workflow for npm, GHCR, and the MCP Registry.
Validates release identity and metadata locally with the same checks used by CI.
Provides an opt-in Gemini CLI extension manifest for gallery discovery.
MCP tools
echo
Echoes a validated message and optional string metadata. It is deliberately simple so the repository teaches MCP schemas, registration, annotations, and results without inventing a business domain.
Example input:
{
"message": "Hello, MCP!",
"metadata": {
"source": "example-client"
}
}Example structured output:
{
"message": "Hello, MCP!",
"metadata": {
"source": "example-client"
}
}Messages are limited to 10,000 characters. Metadata accepts at most 20 entries; keys are limited to 64 characters and values to 1,024 characters.
Tech stack
TypeScript with strict project rules
Installation
Prerequisites
Node.js 24+ and pnpm 11 for local development.
Docker and Docker Compose for container deployment.
Docker Compose
The recommended HTTP deployment uses the published multi-architecture image:
ghcr.io/lukegskw/mcp-typescript-starter:latestDownload the Compose example and provide the hostname clients will use:
curl -O https://raw.githubusercontent.com/lukegskw/mcp-typescript-starter/main/compose.example.yaml
export MCP_ALLOWED_HOSTS='mcp.example.internal'
docker compose -f compose.example.yaml up -dThe Streamable HTTP and health endpoints will be available at:
http://<host>:3000/mcp
http://<host>:3000/healthzTo publish a different host port, set MCP_PUBLISHED_PORT. The application still uses
port 3000 inside the container.
The latest tag follows the newest successful build from the default branch. Use a
version or immutable sha-* tag for controlled deployment and rollback.
Docker run
docker run -d \
--name mcp-typescript-starter \
--restart unless-stopped \
--read-only \
--user 10001:10001 \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--tmpfs /tmp:size=16m,mode=1777 \
-e MCP_TRANSPORT=streamable-http \
-e MCP_HOST=0.0.0.0 \
-e MCP_ALLOWED_HOSTS=127.0.0.1,localhost,mcp.example.internal \
-p 3000:3000 \
ghcr.io/lukegskw/mcp-typescript-starter:latestBuild the container from source
git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
docker buildx build --load -t mcp-typescript-starter:local .Local Node.js installation
git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
pnpm install --frozen-lockfile
pnpm build
pnpm start -- --transport stdioFor local Streamable HTTP development:
MCP_TRANSPORT=streamable-http pnpm devConfiguration
Variable | Required | Default | Description |
| No |
|
|
| No |
| HTTP bind address. |
| No |
| HTTP listening port. |
| Outside loopback | None | Comma-separated Host and Origin hostname allowlist. |
The --transport command-line option overrides MCP_TRANSPORT. MCP_ALLOWED_HOSTS
contains hostnames, not URLs; include every hostname legitimate clients and health
checks use.
The server has no secrets in its example configuration. Add domain credentials through the deployment platform or environment, never as MCP tool arguments or committed files.
MCP client setup
For a client that accepts Streamable HTTP server definitions:
mcp_servers:
starter:
url: http://127.0.0.1:3000/mcpFor a client that launches a local stdio server:
{
"mcpServers": {
"starter": {
"command": "node",
"args": [
"/absolute/path/to/mcp-typescript-starter/dist/main.js",
"--transport",
"stdio"
]
}
}
}After publishing a project derived from this starter, clients can launch its pinned npm package without cloning the repository:
{
"mcpServers": {
"example": {
"command": "npx",
"args": ["--yes", "@example/example-mcp@0.1.0"]
}
}
}When testing the published command from inside its own source checkout, some npm
versions prefer the root package. Use the local node dist/main.js configuration above
or set the MCP server's working directory outside the checkout.
Claude Code and Codex accept the equivalent CLI definitions:
claude mcp add --transport stdio example -- npx --yes @example/example-mcp@0.1.0
codex mcp add example -- npx --yes @example/example-mcp@0.1.0Gemini CLI uses the same mcpServers JSON structure in its settings.json. Add any
domain credentials through each client's environment configuration and keep those files
private.
To let a local client launch the container over stdio, use docker run -i --rm and pass
--transport stdio after the image name. -i is required so the client can exchange
MCP messages through standard input and output.
Client configuration formats differ. Consult the client's documentation for its exact schema and restart or reload the client after changing its server definition.
Customizing the starter
The main extension points are intentionally direct:
Copy or replace
src/tools/echo.ts.Define strict input and output schemas before writing the handler.
Register the tool in
src/server.ts.Add MCP behavior tests and any domain integration tests.
Replace the package name, executable name, server identity, image references, repository metadata, and README content.
Keep
private: trueuntil the distribution checklist below is complete.
Keep tool modules responsible for their own schemas and handlers. Keep transport modules independent from domain tools. Introduce services or persistence only when real behavior requires them.
Treat tool metadata as part of the public API. Describe every input and output field, state prerequisites and side effects in each tool description, publish accurate safety annotations, and add server instructions when callers need to understand a workflow across multiple tools. The behavior test demonstrates how to inspect the definitions an MCP client actually receives.
Distribution and releases
The starter verifies its npm artifact on every pull request but cannot publish by default. This prevents a newly generated repository from releasing under the starter's identity.
To enable distribution in a derived project:
Update
name,bin,repository,homepage,bugs, andkeywordsinpackage.json. AddmcpNamewith the official reverse-DNS MCP name.Copy
server.example.jsontoserver.json, then replace its name, repository, npm identifier, OCI identifier, description, and environment variables. Use an exact OCI version tag, notlatest.Update
SERVER_NAMEinsrc/server.tsand the default MCP server label in theDockerfile.Run
pnpm test:package, then removeprivate: truefrompackage.jsonand runpnpm test:distribution. The distribution check rejects stale versions, mismatched package/Registry/container identities, and remaining starter placeholders.Configure npm Trusted Publishing for
.github/workflows/publish.yml, or add anNPM_TOKENrepository secret as a fallback.Create the repository variable
MCP_RELEASE_ENABLEDwith the valuetrueonly when all identities and registry permissions are ready.
Optional Gemini CLI gallery distribution
To make a derived server installable as a Gemini CLI extension, copy and customize the example manifest:
cp gemini-extension.example.json gemini-extension.jsonReplace the extension name, description, MCP server key, npm package, and any settings.
Represent required credentials with environment substitutions such as
${EXAMPLE_API_KEY} and declare a matching settings entry; mark keys, passwords,
secrets, and tokens as sensitive: true. Add the gemini-cli-extension GitHub topic
after the customized manifest is committed.
The Gemini gallery crawls public
tagged repositories that have that topic and a gemini-extension.json at the repository
root. The release preparation script updates the manifest version automatically when the
optional file exists. Projects that do not create it retain the same release behavior.
Prepare a release with one command:
pnpm release:prepare 0.1.0This synchronizes the package version, Registry version, npm package version, OCI tag,
and optional Gemini extension version. Review and commit the result, run
pnpm test:distribution, then push it to main. The release workflow runs all quality
gates, validates the same distribution contract, creates v0.1.0, and publishes the
versioned container, npm package, MCP Registry entry, and GitHub release.
The regular container workflow owns latest, branch, pull-request, and SHA tags. The
release workflow exclusively owns immutable version tags and checks each external
artifact independently, so rerunning a partial release resumes the missing work.
See the distribution design for the reliability and ownership decisions behind this workflow.
Verification
Run the complete repository suite:
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build
pnpm test:package
pnpm test:distributionFor container changes:
docker buildx build --load -t mcp-typescript-starter:test .Finally, connect an MCP client and confirm that echo is listed and returns both text
and structured content. In HTTP mode, confirm /healthz reports {"status":"ok"}.
Limitations
The example exposes one tool and no resources or prompts.
Streamable HTTP has no authentication. Restrict it to loopback, a trusted LAN, a VPN, a private container network, or an authenticated reverse proxy.
Host and Origin allowlists prevent classes of DNS rebinding attacks but do not authenticate callers.
The HTTP server is stateless and contains no shared persistence or distributed coordination.
Rate limiting, tracing, metrics, and domain-specific logging are not included.
The repository is a source starter, not a published npm library.
Review SECURITY.md before exposing the HTTP transport or reporting a security issue.
Contributing
Contributions are welcome. Before opening a pull request:
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t mcp-typescript-starter:test .Changes must preserve strict typing, bounded validation, structured MCP results, stdout protocol purity, secure HTTP defaults, deterministic tests, and documentation for user-visible behavior. Do not add abstractions without a concrete use case for them.
License
MIT. See LICENSE.
Available Tools
1 toolechoEchoBRead-onlyIdempotent
Echo a validated message and optional string metadata.
Inputs: message (required), metadata. Returns: message, metadata
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion or overlap. The single 'echo' tool is clearly distinct by virtue of being the only tool available.
The single tool name 'echo' is short, clear, and directly describes its function. Since there is only one tool, naming consistency is trivially satisfied.
One tool feels minimal even for a starter server, but it is a common pattern for a simple template. The count is at the lower edge of being acceptable rather than egregiously insufficient.
The server only provides an echo function, which is useful for testing connectivity but lacks any real domain operations. There are no CRUD or workflow capabilities, representing a significant gap for any practical use beyond a basic demo.
Maintenance
Related MCP Connectors
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
A Model Context Protocol server for Wix AI tools
Ovanek MCP: Model Context Protocol server for Ovanek platform tools; writes are dry-run by default.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA stateless Model Context Protocol server that implements a simple echo functionality with resource, tool, and prompt components, enabling LLMs to echo back messages through standardized MCP interactions.1ISC
- AlicenseNot gradedqualityDmaintenanceA minimal Model Context Protocol server that facilitates network-based client connections using Streamable HTTP transport. It provides a greeting tool and is optimized for consistent deployment across local environments, Docker, and Kubernetes.MIT
- AlicenseNot gradedqualityFmaintenanceA robust server implementing the Model Context Protocol with SSE and STDIO transport, enabling real-time communication and extensible tooling for AI models.4MIT
- AlicenseNot gradedqualityDmaintenanceProvides a production-ready Model Context Protocol server with dual STDIO and Streamable HTTP transports, enabling file operations, memory, database queries, RAG, web search, GitHub integration, background tasks, and prompt-based workflows.MIT