mcp-ts-template 2.9.2 → 2.9.9
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.
- package/README.md +22 -30
- package/dist/index.js +104988 -48180
- package/package.json +24 -23
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
<div align="center">
|
|
9
9
|
|
|
10
|
-
[](./CHANGELOG.md) [](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [](https://modelcontextprotocol.io/) [](./LICENSE) [](https://github.com/cyanheads/mcp-ts-template/issues) [](https://www.typescriptlang.org/) [](https://bun.sh/) [](./coverage/index.html)
|
|
11
11
|
|
|
12
12
|
</div>
|
|
13
13
|
|
|
@@ -19,11 +19,10 @@
|
|
|
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`, `
|
|
23
|
-
- **
|
|
24
|
-
- **Full-Stack Observability**: Get deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
|
|
22
|
+
- **Abstracted Storage**: Swap storage backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare D1/KV/R2`) without changing business logic. Features secure opaque cursor pagination, parallel batch operations, and comprehensive validation.
|
|
23
|
+
- **Full-Stack Observability**: Get deep insights with structured logging (Pino) and optional OpenTelemetry for HTTP request tracing, tool-call metrics, and log correlation.
|
|
25
24
|
- **Dependency Injection**: Custom typed DI container with `Token<T>` phantom branding — zero external dependencies, fully type-safe resolution.
|
|
26
|
-
- **Service Integrations**: Pluggable services for external APIs, including LLM providers (OpenRouter)
|
|
25
|
+
- **Service Integrations**: Pluggable services for external APIs, including LLM providers (OpenRouter) and text-to-speech (ElevenLabs).
|
|
27
26
|
- **Rich Built-in Utility Suite**: Helpers for parsing (PDF, YAML, CSV, frontmatter), formatting (diffs, tables, trees, markdown), scheduling, security, and more.
|
|
28
27
|
- **Edge-Ready**: Write code once and run it seamlessly on your local machine or at the edge on Cloudflare Workers.
|
|
29
28
|
|
|
@@ -101,7 +100,7 @@ This template includes working examples to get you started.
|
|
|
101
100
|
|
|
102
101
|
### MCP Client Settings/Configuration
|
|
103
102
|
|
|
104
|
-
Add the following to your MCP
|
|
103
|
+
Add the following to your MCP client configuration file.
|
|
105
104
|
|
|
106
105
|
```json
|
|
107
106
|
{
|
|
@@ -149,26 +148,21 @@ bun install
|
|
|
149
148
|
|
|
150
149
|
All configuration is centralized and validated at startup in `src/config/index.ts`. Key environment variables in your `.env` file include:
|
|
151
150
|
|
|
152
|
-
| Variable
|
|
153
|
-
|
|
|
154
|
-
| `MCP_TRANSPORT_TYPE`
|
|
155
|
-
| `MCP_HTTP_PORT`
|
|
156
|
-
| `MCP_HTTP_HOST`
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `SURREALDB_USERNAME` | **Optional for `surrealdb` storage.** Database username for authentication. | `(none)` |
|
|
168
|
-
| `SURREALDB_PASSWORD` | **Optional for `surrealdb` storage.** Database password for authentication. | `(none)` |
|
|
169
|
-
| `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` |
|
|
170
|
-
| `LOG_LEVEL` | The minimum level for logging (`debug`, `info`, `warn`, `error`). | `info` |
|
|
171
|
-
| `OPENROUTER_API_KEY` | API key for OpenRouter LLM service. | `(none)` |
|
|
151
|
+
| Variable | Description | Default |
|
|
152
|
+
| :------------------------ | :--------------------------------------------------------------------------------------------------------- | :----------- |
|
|
153
|
+
| `MCP_TRANSPORT_TYPE` | The transport to use: `stdio` or `http`. | `stdio` |
|
|
154
|
+
| `MCP_HTTP_PORT` | The port for the HTTP server. | `3010` |
|
|
155
|
+
| `MCP_HTTP_HOST` | The hostname for the HTTP server. | `127.0.0.1` |
|
|
156
|
+
| `MCP_LOG_LEVEL` | Logging level (`fatal`, `error`, `warn`, `info`, `debug`, `trace`, `silent`). | `debug` |
|
|
157
|
+
| `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |
|
|
158
|
+
| `MCP_AUTH_SECRET_KEY` | **Required for `jwt` auth mode.** A 32+ character secret. | `(none)` |
|
|
159
|
+
| `OAUTH_ISSUER_URL` | **Required for `oauth` auth mode.** URL of the OIDC provider. | `(none)` |
|
|
160
|
+
| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-d1`, `cloudflare-kv`, `cloudflare-r2`. | `in-memory` |
|
|
161
|
+
| `STORAGE_FILESYSTEM_PATH` | Path to the storage directory (for `filesystem` provider). | `./.storage` |
|
|
162
|
+
| `SUPABASE_URL` | **Required for `supabase` storage.** Your Supabase project URL. | `(none)` |
|
|
163
|
+
| `SUPABASE_ANON_KEY` | **Required for `supabase` storage.** Your Supabase anon key. | `(none)` |
|
|
164
|
+
| `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` |
|
|
165
|
+
| `OPENROUTER_API_KEY` | API key for OpenRouter LLM service. | `(none)` |
|
|
172
166
|
|
|
173
167
|
### Authentication & Authorization
|
|
174
168
|
|
|
@@ -178,8 +172,7 @@ All configuration is centralized and validated at startup in `src/config/index.t
|
|
|
178
172
|
### Storage
|
|
179
173
|
|
|
180
174
|
- **Service**: A DI-managed `StorageService` provides a consistent API for persistence. **Never access `fs` or other storage SDKs directly from tool logic.**
|
|
181
|
-
- **Providers**: The default is `in-memory`. Node-only providers include `filesystem`. Edge-compatible providers include `supabase`, `
|
|
182
|
-
- **SurrealDB Setup**: When using `surrealdb` provider, initialize the database schema using `docs/surrealdb-schema.surql` before first use.
|
|
175
|
+
- **Providers**: The default is `in-memory`. Node-only providers include `filesystem`. Edge-compatible providers include `supabase`, `cloudflare-kv`, and `cloudflare-r2`.
|
|
183
176
|
- **Multi-Tenancy**: The `StorageService` requires `context.tenantId`. This is automatically propagated from the `tid` claim in a JWT when auth is enabled.
|
|
184
177
|
- **Advanced Features**:
|
|
185
178
|
- **Secure Pagination**: Opaque cursors with tenant ID binding prevent cross-tenant attacks
|
|
@@ -190,7 +183,7 @@ All configuration is centralized and validated at startup in `src/config/index.t
|
|
|
190
183
|
### Observability
|
|
191
184
|
|
|
192
185
|
- **Structured Logging**: Pino is integrated out-of-the-box. All logs are JSON and include the `RequestContext`.
|
|
193
|
-
- **OpenTelemetry**: Disabled by default. Enable with `OTEL_ENABLED=true` and configure OTLP endpoints.
|
|
186
|
+
- **OpenTelemetry**: Disabled by default. Enable with `OTEL_ENABLED=true` and configure OTLP endpoints. HTTP request-level spans are generated via `@hono/otel` (works on Bun, where Node.js auto-instrumentation is a no-op). Tool-call metrics (duration, payload sizes, errors) are captured automatically. Pino logs auto-correlate to traces via `trace_id`/`span_id`.
|
|
194
187
|
|
|
195
188
|
## ▶️ Running the Server
|
|
196
189
|
|
|
@@ -274,7 +267,6 @@ Each major module includes comprehensive documentation with architecture diagram
|
|
|
274
267
|
- **[Services Guide](src/services/)** - External service integration patterns
|
|
275
268
|
- LLM provider integration (OpenRouter)
|
|
276
269
|
- Speech services (TTS/STT with ElevenLabs, Whisper)
|
|
277
|
-
- Graph database operations (SurrealDB)
|
|
278
270
|
- Creating custom service providers
|
|
279
271
|
- Health checks and error handling
|
|
280
272
|
|