mcp-ts-template 2.4.3 → 2.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +24 -18
  2. package/dist/index.js +1 -1
  3. package/package.json +34 -31
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-2.4.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--06--18-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.20.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/mcp-ts-template/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2.23-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Code Coverage](https://img.shields.io/badge/Coverage-75.89%25-brightgreen.svg?style=flat-square)](./coverage/index.html)
10
+ [![Version](https://img.shields.io/badge/Version-2.4.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--06--18-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.20.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/mcp-ts-template/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2.23-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Code Coverage](https://img.shields.io/badge/Coverage-76.12%25-brightgreen.svg?style=flat-square)](./coverage/index.html)
11
11
 
12
12
  </div>
13
13
 
@@ -19,7 +19,7 @@
19
19
  - **Elicitation Support**: Tools can interactively prompt the user for missing parameters during execution, streamlining user workflows.
20
20
  - **Robust Error Handling**: A unified `McpError` system ensures consistent, structured error responses across the server.
21
21
  - **Pluggable Authentication**: Secure your server with zero-fuss support for `none`, `jwt`, or `oauth` modes.
22
- - **Abstracted Storage**: Swap storage backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2`) without changing business logic. Features secure opaque cursor pagination, parallel batch operations, and comprehensive validation.
22
+ - **Abstracted Storage**: Swap storage backends (`in-memory`, `filesystem`, `Supabase`, `SurrealDB`, `Cloudflare KV/R2`) without changing business logic. Features secure opaque cursor pagination, parallel batch operations, and comprehensive validation.
23
23
  - **Full-Stack Observability**: Get deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
24
24
  - **Dependency Injection**: Built with `tsyringe` for a clean, decoupled, and testable architecture.
25
25
  - **Service Integrations**: Pluggable services for external APIs, including LLM providers (OpenRouter) and text-to-speech (ElevenLabs).
@@ -104,21 +104,26 @@ bun install
104
104
 
105
105
  All configuration is centralized and validated at startup in `src/config/index.ts`. Key environment variables in your `.env` file include:
106
106
 
107
- | Variable | Description | Default |
108
- | :-------------------------- | :----------------------------------------------------------------------------- | :---------- |
109
- | `MCP_TRANSPORT_TYPE` | The transport to use: `stdio` or `http`. | `http` |
110
- | `MCP_HTTP_PORT` | The port for the HTTP server. | `3010` |
111
- | `MCP_HTTP_HOST` | The hostname for the HTTP server. | `127.0.0.1` |
112
- | `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |
113
- | `MCP_AUTH_SECRET_KEY` | **Required for `jwt` auth mode.** A 32+ character secret. | `(none)` |
114
- | `OAUTH_ISSUER_URL` | **Required for `oauth` auth mode.** URL of the OIDC provider. | `(none)` |
115
- | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv`, `r2`. | `in-memory` |
116
- | `STORAGE_FILESYSTEM_PATH` | **Required for `filesystem` storage.** Path to the storage directory. | `(none)` |
117
- | `SUPABASE_URL` | **Required for `supabase` storage.** Your Supabase project URL. | `(none)` |
118
- | `SUPABASE_SERVICE_ROLE_KEY` | **Required for `supabase` storage.** Your Supabase service role key. | `(none)` |
119
- | `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` |
120
- | `LOG_LEVEL` | The minimum level for logging (`debug`, `info`, `warn`, `error`). | `info` |
121
- | `OPENROUTER_API_KEY` | API key for OpenRouter LLM service. | `(none)` |
107
+ | Variable | Description | Default |
108
+ | :-------------------------- | :------------------------------------------------------------------------------------------------ | :---------- |
109
+ | `MCP_TRANSPORT_TYPE` | The transport to use: `stdio` or `http`. | `http` |
110
+ | `MCP_HTTP_PORT` | The port for the HTTP server. | `3010` |
111
+ | `MCP_HTTP_HOST` | The hostname for the HTTP server. | `127.0.0.1` |
112
+ | `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |
113
+ | `MCP_AUTH_SECRET_KEY` | **Required for `jwt` auth mode.** A 32+ character secret. | `(none)` |
114
+ | `OAUTH_ISSUER_URL` | **Required for `oauth` auth mode.** URL of the OIDC provider. | `(none)` |
115
+ | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `surrealdb`, `cloudflare-kv`, `r2`. | `in-memory` |
116
+ | `STORAGE_FILESYSTEM_PATH` | **Required for `filesystem` storage.** Path to the storage directory. | `(none)` |
117
+ | `SUPABASE_URL` | **Required for `supabase` storage.** Your Supabase project URL. | `(none)` |
118
+ | `SUPABASE_SERVICE_ROLE_KEY` | **Required for `supabase` storage.** Your Supabase service role key. | `(none)` |
119
+ | `SURREALDB_URL` | **Required for `surrealdb` storage.** SurrealDB endpoint (e.g., `wss://cloud.surrealdb.com/rpc`). | `(none)` |
120
+ | `SURREALDB_NAMESPACE` | **Required for `surrealdb` storage.** SurrealDB namespace. | `(none)` |
121
+ | `SURREALDB_DATABASE` | **Required for `surrealdb` storage.** SurrealDB database name. | `(none)` |
122
+ | `SURREALDB_USERNAME` | **Optional for `surrealdb` storage.** Database username for authentication. | `(none)` |
123
+ | `SURREALDB_PASSWORD` | **Optional for `surrealdb` storage.** Database password for authentication. | `(none)` |
124
+ | `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` |
125
+ | `LOG_LEVEL` | The minimum level for logging (`debug`, `info`, `warn`, `error`). | `info` |
126
+ | `OPENROUTER_API_KEY` | API key for OpenRouter LLM service. | `(none)` |
122
127
 
123
128
  ### Authentication & Authorization
124
129
 
@@ -128,7 +133,8 @@ All configuration is centralized and validated at startup in `src/config/index.t
128
133
  ### Storage
129
134
 
130
135
  - **Service**: A DI-managed `StorageService` provides a consistent API for persistence. **Never access `fs` or other storage SDKs directly from tool logic.**
131
- - **Providers**: The default is `in-memory`. Node-only providers include `filesystem`. Edge-compatible providers include `supabase`, `cloudflare-kv`, and `cloudflare-r2`.
136
+ - **Providers**: The default is `in-memory`. Node-only providers include `filesystem`. Edge-compatible providers include `supabase`, `surrealdb`, `cloudflare-kv`, and `cloudflare-r2`.
137
+ - **SurrealDB Setup**: When using `surrealdb` provider, initialize the database schema using `docs/surrealdb-schema.surql` before first use.
132
138
  - **Multi-Tenancy**: The `StorageService` requires `context.tenantId`. This is automatically propagated from the `tid` claim in a JWT when auth is enabled.
133
139
  - **Advanced Features**:
134
140
  - **Secure Pagination**: Opaque cursors with tenant ID binding prevent cross-tenant attacks
package/dist/index.js CHANGED
@@ -117141,7 +117141,7 @@ var z = /* @__PURE__ */ Object.freeze({
117141
117141
  // package.json
117142
117142
  var package_default = {
117143
117143
  name: "mcp-ts-template",
117144
- version: "2.4.2",
117144
+ version: "2.4.3",
117145
117145
  mcpName: "io.github.cyanheads/mcp-ts-template",
117146
117146
  description: "The definitive, production-grade template for building powerful and scalable Model Context Protocol (MCP) servers with TypeScript, featuring built-in observability (OpenTelemetry), declarative tooling, robust error handling, and a modular, DI-driven architecture.",
117147
117147
  main: "dist/index.js",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-ts-template",
3
- "version": "2.4.3",
3
+ "version": "2.4.5",
4
4
  "mcpName": "io.github.cyanheads/mcp-ts-template",
5
5
  "description": "The definitive, production-grade template for building powerful and scalable Model Context Protocol (MCP) servers with TypeScript, featuring built-in observability (OpenTelemetry), declarative tooling, robust error handling, and a modular, DI-driven architecture.",
6
6
  "main": "dist/index.js",
@@ -54,6 +54,8 @@
54
54
  "inspector": "bunx mcp-inspector --config mcp.json --server mcp-ts-template",
55
55
  "test": "bunx vitest run",
56
56
  "test:coverage": "bunx vitest run --coverage",
57
+ "coverage:update": "bun run scripts/update-coverage.ts",
58
+ "coverage:commit": "bun run scripts/update-coverage.ts --commit",
57
59
  "audit": "bun audit",
58
60
  "audit:fix": "bun audit --fix",
59
61
  "publish-mcp": "bun scripts/validate-mcp-publish-schema.ts"
@@ -66,33 +68,12 @@
66
68
  "zod": "3.23.8",
67
69
  "typescript": "5.9.3"
68
70
  },
69
- "dependencies": {
71
+ "devDependencies": {
72
+ "@cloudflare/workers-types": "^4.20251011.0",
73
+ "@eslint/js": "^9.37.0",
70
74
  "@hono/mcp": "^0.1.4",
71
75
  "@hono/node-server": "^1.19.5",
72
76
  "@modelcontextprotocol/sdk": "^1.20.0",
73
- "@supabase/supabase-js": "^2.75.0",
74
- "axios": "^1.12.2",
75
- "chrono-node": "^2.9.0",
76
- "dotenv": "^17.2.3",
77
- "fast-xml-parser": "^5.3.0",
78
- "hono": "^4.9.12",
79
- "ignore": "^7.0.5",
80
- "jose": "^6.1.0",
81
- "js-yaml": "^4.1.0",
82
- "node-cron": "^4.2.1",
83
- "openai": "^6.3.0",
84
- "papaparse": "^5.5.3",
85
- "partial-json": "^0.1.7",
86
- "pdf-lib": "^1.17.1",
87
- "pino": "^10.0.0",
88
- "pino-pretty": "^13.1.2",
89
- "reflect-metadata": "^0.2.2",
90
- "repomix": "^1.7.0",
91
- "sanitize-html": "^2.17.0",
92
- "tslib": "^2.8.1",
93
- "tsyringe": "^4.10.0",
94
- "validator": "13.15.15",
95
- "zod": "^3.23.8",
96
77
  "@opentelemetry/api": "^1.9.0",
97
78
  "@opentelemetry/auto-instrumentations-node": "^0.65.0",
98
79
  "@opentelemetry/exporter-metrics-otlp-http": "^0.206.0",
@@ -102,11 +83,8 @@
102
83
  "@opentelemetry/sdk-metrics": "^2.1.0",
103
84
  "@opentelemetry/sdk-node": "^0.206.0",
104
85
  "@opentelemetry/sdk-trace-node": "^2.1.0",
105
- "@opentelemetry/semantic-conventions": "^1.37.0"
106
- },
107
- "devDependencies": {
108
- "@cloudflare/workers-types": "^4.20251011.0",
109
- "@eslint/js": "^9.37.0",
86
+ "@opentelemetry/semantic-conventions": "^1.37.0",
87
+ "@supabase/supabase-js": "^2.75.0",
110
88
  "@types/bun": "^1.3.0",
111
89
  "@types/js-yaml": "^4.0.9",
112
90
  "@types/node": "^24.7.2",
@@ -117,21 +95,43 @@
117
95
  "@vitest/coverage-v8": "3.2.4",
118
96
  "ajv": "^8.17.1",
119
97
  "ajv-formats": "^3.0.1",
98
+ "axios": "^1.12.2",
120
99
  "bun-types": "^1.3.0",
100
+ "chrono-node": "^2.9.0",
121
101
  "clipboardy": "^5.0.0",
122
102
  "depcheck": "^1.4.7",
103
+ "dotenv": "^17.2.3",
123
104
  "eslint": "^9.37.0",
124
105
  "execa": "^9.6.0",
106
+ "fast-xml-parser": "^5.3.0",
125
107
  "globals": "^16.4.0",
108
+ "hono": "^4.9.12",
126
109
  "husky": "^9.1.7",
110
+ "ignore": "^7.0.5",
111
+ "jose": "^6.1.0",
112
+ "js-yaml": "^4.1.0",
127
113
  "msw": "^2.11.5",
114
+ "node-cron": "^4.2.1",
115
+ "openai": "^6.3.0",
116
+ "papaparse": "^5.5.3",
117
+ "partial-json": "^0.1.7",
118
+ "pdf-lib": "^1.17.1",
119
+ "pino": "^10.0.0",
120
+ "pino-pretty": "^13.1.2",
128
121
  "prettier": "^3.6.2",
122
+ "reflect-metadata": "^0.2.2",
123
+ "repomix": "^1.7.0",
124
+ "sanitize-html": "^2.17.0",
125
+ "tslib": "^2.8.1",
126
+ "tsyringe": "^4.10.0",
129
127
  "typedoc": "^0.28.14",
130
128
  "typescript": "^5.9.3",
131
129
  "typescript-eslint": "8.46.1",
130
+ "validator": "13.15.15",
132
131
  "vite": "7.1.10",
133
132
  "vite-tsconfig-paths": "^5.1.4",
134
- "vitest": "^3.2.4"
133
+ "vitest": "^3.2.4",
134
+ "zod": "^3.23.8"
135
135
  },
136
136
  "keywords": [
137
137
  "agent",
@@ -182,5 +182,8 @@
182
182
  },
183
183
  "publishConfig": {
184
184
  "access": "public"
185
+ },
186
+ "dependencies": {
187
+ "surrealdb": "^1.3.2"
185
188
  }
186
189
  }