Helvetium MCP
README.md
<div align="center">
<img src="https://github.com/newfoundcodes/newfoundcodes-logo/blob/main/newfoundcodes-helvetium.png?raw=true" width="128" />
<h1>Helvetium MCP</h1>
<p>
<a href="https://github.com/newfoundcodes/helvetium-mcp/actions"><img src="https://github.com/newfoundcodes/helvetium-mcp/actions/workflows/ci.yml/badge.svg" alt="Build Status"></a>
</p>
</div>
Standalone TypeScript implementation of Model Context Protocol **2026-07-28**. It is designed to let AI agents communicate with Helvetium Boot services or any Fetch/stdin-stdout host without importing the official MCP SDK.
## Protocol model
MCP 2026-07-28 is stateless at the protocol layer. Helvetium MCP implements this futuristic stateless architecture natively, but it also features a built-in backward-compatibility layer. It seamlessly handles legacy `initialize` handshakes and omits the need for `_meta` fields when communicating with older standard clients. This means it works out-of-the-box with both stateful 2024-11-05 clients and stateless 2026-07-28 clients. Every request in the new protocol carries its protocol version and client capabilities in `_meta`. The optional `server/discover` call exposes server capabilities. Streamable HTTP requests mirror routing data in `MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`, and optional `Mcp-Param-*` headers.
## Install
```bash
npm install @newfoundcodes/helvetium-mcp
```
Helvetium Boot is optional:
```bash
npm install @newfoundcodes/helvetium-boot
```
## Minimal server
```typescript
import { MCPServer, type McpTool } from '@newfoundcodes/helvetium-mcp';
const mcpServer = new MCPServer({
name: 'my-mcp-server',
version: '1.0.0',
});
// Define tools cleanly using the McpTool type
export function pingTool(): McpTool {
return {
description: 'Ping tool to check server status',
inputSchema: { type: 'object', properties: {}, additionalProperties: true },
handler: async (args, context) => {
return {
status: 'pong',
};
},
};
}
mcpServer.tool('ping', pingTool());
```
## Helvetium Boot
In a standard Helvetium project generated by the CLI, an MCP server is already scaffolded inside `src/routes/paths.ts` and mounted on the `/mcp` route using `mountMCP`. An example tool is generated in `src/routes/mcp/ping.ts`.
To manually wire an MCP server into a Helvetium Boot application:
```ts
import { createApp } from '@newfoundcodes/helvetium-boot';
import { createMCPServer, mountMCP } from '@newfoundcodes/helvetium-mcp';
const app = createApp();
const mcp = createMCPServer({ name: 'boot-mcp', version: '1.0.0' });
mcp.tool('health', () => ({ healthy: true }));
mountMCP(app, mcp, { path: '/mcp' });
```
## Security
MCP metadata does not authorize a request. Protect sensitive tools and resources with real identity and object-level authorization. Validate OAuth/JWT tokens before handlers run, use TLS, restrict Origins for browser-accessible HTTP endpoints, apply body/time/rate limits, honor cancellation, and never forward the caller's bearer token blindly to upstream systems.
## JSON Schema note
Tool schemas remain ordinary JSON Schema on the MCP wire. The dependency-free built-in validator covers common structural and constraint keywords and is used for basic input/output checking. It is not presented as a complete general JSON Schema 2020-12 engine. Applications that depend on advanced schema keywords should perform an additional validation pass with their chosen standards-complete validator.
## Authoritative MCP baseline
- https://modelcontextprotocol.io/specification/2026-07-28
- https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2026-07-28/schema.ts
- https://blog.modelcontextprotocol.io/posts/2026-07-28/
## License
This project is licensed under the [AGPL-3.0-only](https://spdx.org/licenses/AGPL-3.0-only.html) License.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues