mcp-ts-template 2.9.3 → 3.0.0

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 +126 -160
  2. package/dist/index.js +154359 -180487
  3. package/package.json +43 -44
package/README.md CHANGED
@@ -1,35 +1,36 @@
1
1
  <div align="center">
2
2
  <h1>mcp-ts-template</h1>
3
- <p><b>TypeScript template for building Model Context Protocol (MCP) servers. Ships with declarative tools/resources, pluggable auth, multi-backend storage, OpenTelemetry observability, and first-class support for both local and edge (Cloudflare Workers) runtimes.</b>
3
+ <p><b>TypeScript template for building Model Context Protocol (MCP) servers. Ships with declarative tools/resources, pluggable auth, multi-backend storage, OpenTelemetry observability, and support for both local and edge (Cloudflare Workers) runtimes.</b>
4
4
  <div>7 Tools • 2 Resources • 1 Prompt</div>
5
5
  </p>
6
6
  </div>
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-2.9.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.26.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.21-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Code Coverage](https://img.shields.io/badge/Coverage-86.30%25-brightgreen.svg?style=flat-square)](./coverage/index.html)
10
+ [![Version](https://img.shields.io/badge/Version-3.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
11
+
12
+ [![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.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Code Coverage](https://img.shields.io/badge/Coverage-86.30%25-brightgreen.svg?style=flat-square)](./coverage/index.html)
11
13
 
12
14
  </div>
13
15
 
14
16
  ---
15
17
 
16
- ## Features
18
+ ## Features
17
19
 
18
- - **Declarative Tools & Resources**: Define capabilities in single, self-contained files. The framework handles registration and execution.
19
- - **Elicitation Support**: Tools can interactively prompt the user for missing parameters during execution, streamlining user workflows.
20
- - **Robust Error Handling**: A unified `McpError` system ensures consistent, structured error responses across the server.
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`, `SurrealDB`, `Cloudflare D1/KV/R2`) without changing business logic. Features secure opaque cursor pagination, parallel batch operations, and comprehensive validation.
23
- - **Graph Database Operations**: Optional graph service for relationship management, graph traversals, and pathfinding algorithms (SurrealDB provider).
24
- - **Full-Stack Observability**: Get deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
25
- - **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), text-to-speech (ElevenLabs), and graph operations (SurrealDB).
27
- - **Rich Built-in Utility Suite**: Helpers for parsing (PDF, YAML, CSV, frontmatter), formatting (diffs, tables, trees, markdown), scheduling, security, and more.
28
- - **Edge-Ready**: Write code once and run it seamlessly on your local machine or at the edge on Cloudflare Workers.
20
+ - Define tools and resources in single, self-contained files. The framework handles registration.
21
+ - Tools can prompt users for missing parameters mid-execution via elicitation.
22
+ - Unified `McpError` system for consistent, structured error responses.
23
+ - Auth modes: `none`, `jwt`, or `oauth`. Wrap logic with `withToolAuth`/`withResourceAuth`.
24
+ - Swap storage backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare D1/KV/R2`) without changing tool logic. Includes cursor pagination, batch ops, and input validation.
25
+ - Structured logging (Pino) with optional OpenTelemetry for tracing and metrics.
26
+ - Custom typed DI container with `Token<T>` phantom branding. No external deps.
27
+ - Pluggable service integrations: LLM (OpenRouter), TTS (ElevenLabs).
28
+ - Parsing helpers (PDF, YAML, CSV, frontmatter), formatting (diffs, tables, trees, markdown), scheduling, security.
29
+ - Runs on local (stdio/HTTP) and edge (Cloudflare Workers) with the same code.
29
30
 
30
- ## 🏗️ Architecture
31
+ ## Architecture
31
32
 
32
- This template follows a modular, domain-driven architecture with clear separation of concerns:
33
+ Modular, domain-driven layout with clear separation of concerns:
33
34
 
34
35
  ```
35
36
  ┌─────────────────────────────────────────────────────────┐
@@ -39,36 +40,34 @@ This template follows a modular, domain-driven architecture with clear separatio
39
40
 
40
41
  ┌─────────────────────────────────────────────────────────┐
41
42
  │ MCP Server (Tools, Resources) │
42
- 📖 [MCP Server Guide](src/mcp-server/)
43
+ [MCP Server Guide](src/mcp-server/)
43
44
  └────────────────────┬────────────────────────────────────┘
44
45
  │ Dependency Injection
45
46
 
46
47
  ┌─────────────────────────────────────────────────────────┐
47
48
  │ Dependency Injection Container │
48
- 📦 [Container Guide](src/container/)
49
+ │ [Container Guide](src/container/)
49
50
  └────────────────────┬────────────────────────────────────┘
50
51
 
51
52
  ┌────────────┼────────────┐
52
53
  ▼ ▼ ▼
53
54
  ┌──────────┐ ┌──────────┐ ┌──────────┐
54
55
  │ Services │ │ Storage │ │ Utilities│
55
- 🔌 [→] │ │ 💾 [→] │ │ 🛠️ [→] │
56
+ [→] │ │ [→] │ │ [→] │
56
57
  └──────────┘ └──────────┘ └──────────┘
57
58
 
58
59
  [→]: src/services/ [→]: src/storage/ [→]: src/utils/
59
60
  ```
60
61
 
61
- **Key Modules:**
62
-
63
- - **[MCP Server](src/mcp-server/)** - Tools, resources, prompts, and transport layer implementations
64
- - **[Container](src/container/)** - Typed dependency injection container with zero external dependencies
65
- - **[Services](src/services/)** - External service integrations (LLM, Speech, Graph) with pluggable providers
66
- - **[Storage](src/storage/)** - Abstracted persistence layer with multiple backend support
67
- - **[Utilities](src/utils/)** - Cross-cutting concerns (logging, security, parsing, telemetry)
62
+ Key modules:
68
63
 
69
- > 💡 **Tip**: Each module has its own comprehensive README with architecture diagrams, usage examples, and best practices. Click the links above to dive deeper!
64
+ - [MCP Server](src/mcp-server/) Tools, resources, prompts, and transport layer
65
+ - [Container](src/container/) — Typed DI container, no external deps
66
+ - [Services](src/services/) — External integrations (LLM, Speech, Graph) with pluggable providers
67
+ - [Storage](src/storage/) — Persistence layer with multiple backend support
68
+ - [Utilities](src/utils/) — Logging, security, parsing, telemetry
70
69
 
71
- ## 🛠️ Included Capabilities
70
+ ## Included capabilities
72
71
 
73
72
  This template includes working examples to get you started.
74
73
 
@@ -97,11 +96,11 @@ This template includes working examples to get you started.
97
96
  | :---------------- | :--------------------------------------------------------------- |
98
97
  | **`code-review`** | A structured prompt for guiding an LLM to perform a code review. |
99
98
 
100
- ## 🚀 Getting Started
99
+ ## Getting started
101
100
 
102
- ### MCP Client Settings/Configuration
101
+ ### MCP client configuration
103
102
 
104
- Add the following to your MCP Client configuration file (e.g., `cline_mcp_settings.json`).
103
+ Add the following to your MCP client configuration file.
105
104
 
106
105
  ```json
107
106
  {
@@ -123,7 +122,7 @@ Add the following to your MCP Client configuration file (e.g., `cline_mcp_settin
123
122
 
124
123
  ### Prerequisites
125
124
 
126
- - [Bun v1.2.21](https://bun.sh/) or higher.
125
+ - [Bun v1.2.0](https://bun.sh/) or higher.
127
126
 
128
127
  ### Installation
129
128
 
@@ -145,183 +144,150 @@ cd mcp-ts-template
145
144
  bun install
146
145
  ```
147
146
 
148
- ## ⚙️ Configuration
147
+ ## Configuration
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 | Description | Default |
153
- | :-------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :---------- |
154
- | `MCP_TRANSPORT_TYPE` | The transport to use: `stdio` or `http`. | `http` |
155
- | `MCP_HTTP_PORT` | The port for the HTTP server. | `3010` |
156
- | `MCP_HTTP_HOST` | The hostname for the HTTP server. | `127.0.0.1` |
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`, `surrealdb`, `cloudflare-d1`, `cloudflare-kv`, `cloudflare-r2`. | `in-memory` |
161
- | `STORAGE_FILESYSTEM_PATH` | **Required for `filesystem` storage.** Path to the storage directory. | `(none)` |
162
- | `SUPABASE_URL` | **Required for `supabase` storage.** Your Supabase project URL. | `(none)` |
163
- | `SUPABASE_SERVICE_ROLE_KEY` | **Required for `supabase` storage.** Your Supabase service role key. | `(none)` |
164
- | `SURREALDB_URL` | **Required for `surrealdb` storage.** SurrealDB endpoint (e.g., `wss://cloud.surrealdb.com/rpc`). | `(none)` |
165
- | `SURREALDB_NAMESPACE` | **Required for `surrealdb` storage.** SurrealDB namespace. | `(none)` |
166
- | `SURREALDB_DATABASE` | **Required for `surrealdb` storage.** SurrealDB database name. | `(none)` |
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)` |
172
-
173
- ### Authentication & Authorization
174
-
175
- - **Modes**: `none` (default), `jwt` (requires `MCP_AUTH_SECRET_KEY`), or `oauth` (requires `OAUTH_ISSUER_URL` and `OAUTH_AUDIENCE`).
176
- - **Enforcement**: Wrap your tool/resource `logic` functions with `withToolAuth([...])` or `withResourceAuth([...])` to enforce scope checks. Scope checks are bypassed for developer convenience when auth mode is `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 (`debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`). | `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
+ | `DEV_MCP_AUTH_BYPASS` | Set to `true` to bypass JWT auth in development (requires no secret key). | `false` |
160
+ | `OAUTH_ISSUER_URL` | **Required for `oauth` auth mode.** URL of the OIDC provider. | `(none)` |
161
+ | `OAUTH_AUDIENCE` | **Required for `oauth` auth mode.** Expected audience claim in the JWT. | `(none)` |
162
+ | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-d1`, `cloudflare-kv`, `cloudflare-r2`. | `in-memory` |
163
+ | `STORAGE_FILESYSTEM_PATH` | Path to the storage directory (for `filesystem` provider). | `./.storage` |
164
+ | `SUPABASE_URL` | **Required for `supabase` storage.** Your Supabase project URL. | `(none)` |
165
+ | `SUPABASE_ANON_KEY` | **Required for `supabase` storage.** Your Supabase anon key. | `(none)` |
166
+ | `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` |
167
+ | `OPENROUTER_API_KEY` | API key for OpenRouter LLM service. | `(none)` |
168
+
169
+ ### Authentication and authorization
170
+
171
+ - Modes: `none` (default), `jwt` (requires `MCP_AUTH_SECRET_KEY`), or `oauth` (requires `OAUTH_ISSUER_URL` and `OAUTH_AUDIENCE`).
172
+ - In development, set `DEV_MCP_AUTH_BYPASS=true` to skip JWT validation without a secret key. Rejected in production.
173
+ - Wrap tool/resource `logic` with `withToolAuth([...])` or `withResourceAuth([...])` for scope checks. Checks are bypassed when auth mode is `none`.
177
174
 
178
175
  ### Storage
179
176
 
180
- - **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`, `surrealdb`, `cloudflare-kv`, and `cloudflare-r2`.
182
- - **SurrealDB Setup**: When using `surrealdb` provider, initialize the database schema using `docs/surrealdb-schema.surql` before first use.
183
- - **Multi-Tenancy**: The `StorageService` requires `context.tenantId`. This is automatically propagated from the `tid` claim in a JWT when auth is enabled.
184
- - **Advanced Features**:
185
- - **Secure Pagination**: Opaque cursors with tenant ID binding prevent cross-tenant attacks
186
- - **Batch Operations**: Parallel execution for `getMany()`, `setMany()`, `deleteMany()`
187
- - **TTL Support**: Time-to-live with proper expiration handling across all providers
188
- - **Comprehensive Validation**: Centralized input validation for tenant IDs, keys, and options
177
+ - DI-managed `StorageService` provides a consistent API for persistence. Never access `fs` or storage SDKs directly from tool logic.
178
+ - Default provider is `in-memory`. Node-only: `filesystem`. Edge-compatible: `supabase`, `cloudflare-kv`, `cloudflare-r2`.
179
+ - `StorageService` requires `context.tenantId`, auto-propagated from the JWT `tid` claim when auth is enabled.
180
+ - Opaque cursor pagination with tenant binding, parallel batch ops (`getMany`/`setMany`/`deleteMany`), TTL support, centralized input validation.
189
181
 
190
182
  ### Observability
191
183
 
192
- - **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. Traces, metrics (duration, payload sizes), and errors are automatically captured for every tool call.
184
+ - Pino for structured JSON logging. All logs include `RequestContext`.
185
+ - OpenTelemetry disabled by default. Enable with `OTEL_ENABLED=true`. HTTP spans via `@hono/otel` (works on Bun). Tool-call metrics (duration, payload sizes, errors) captured automatically. Pino logs correlate to traces via `trace_id`/`span_id`.
194
186
 
195
- ## ▶️ Running the Server
187
+ ## Running the server
196
188
 
197
- ### Local Development
189
+ ### Local development
198
190
 
199
191
  - **Build and run the production version**:
200
192
 
201
193
  ```sh
202
194
  # One-time build
203
- bun rebuild
195
+ bun run rebuild
204
196
 
205
197
  # Run the built server
206
- bun start:http
198
+ bun run start:http
207
199
  # or
208
- bun start:stdio
200
+ bun run start:stdio
209
201
  ```
210
202
 
211
203
  - **Run checks and tests**:
212
204
  ```sh
213
- bun devcheck # Lints, formats, type-checks, and more
205
+ bun run devcheck # Lints, formats, type-checks, and more
214
206
  bun run test # Runs the test suite (Do not use 'bun test' directly as it may not work correctly)
215
207
  ```
216
208
 
217
- ### Cloudflare Workers
209
+ ### Cloudflare workers
218
210
 
219
211
  1. **Build the Worker bundle**:
220
212
 
221
213
  ```sh
222
- bun build:worker
214
+ bun run build:worker
223
215
  ```
224
216
 
225
217
  2. **Run locally with Wrangler**:
226
218
 
227
219
  ```sh
228
- bun deploy:dev
220
+ bun run deploy:dev
229
221
  ```
230
222
 
231
223
  3. **Deploy to Cloudflare**:
232
224
 
233
225
  ```sh
234
- bun deploy:prod
226
+ bun run deploy:prod
235
227
  ```
236
228
 
237
229
  > **Note**: The `wrangler.toml` file is pre-configured to enable `nodejs_compat` for best results.
238
230
 
239
- ## 📂 Project Structure
240
-
241
- | Directory | Purpose & Contents | Guide |
242
- | :------------------------------------- | :----------------------------------------------------------------------------------- | :----------------------------------- |
243
- | `src/mcp-server/tools/definitions` | Your tool definitions (`*.tool.ts`). This is where you add new capabilities. | [📖 MCP Guide](src/mcp-server/) |
244
- | `src/mcp-server/resources/definitions` | Your resource definitions (`*.resource.ts`). This is where you add new data sources. | [📖 MCP Guide](src/mcp-server/) |
245
- | `src/mcp-server/transports` | Implementations for HTTP and STDIO transports, including auth middleware. | [📖 MCP Guide](src/mcp-server/) |
246
- | `src/storage` | The `StorageService` abstraction and all storage provider implementations. | [💾 Storage Guide](src/storage/) |
247
- | `src/services` | Integrations with external services (e.g., the default OpenRouter LLM provider). | [🔌 Services Guide](src/services/) |
248
- | `src/container` | Dependency injection container registrations and tokens. | [📦 Container Guide](src/container/) |
249
- | `src/utils` | Core utilities for logging, error handling, performance, security, and telemetry. | |
250
- | `src/config` | Environment variable parsing and validation with Zod. | |
251
- | `tests/` | Unit and integration tests, mirroring the `src/` directory structure. | |
252
-
253
- ## 📚 Documentation
254
-
255
- Each major module includes comprehensive documentation with architecture diagrams, usage examples, and best practices:
256
-
257
- ### Core Modules
258
-
259
- - **[MCP Server Guide](src/mcp-server/)** - Complete guide to building MCP tools and resources
260
- - Creating tools with declarative definitions
261
- - Resource development with URI templates
262
- - Authentication and authorization
263
- - Transport layer (HTTP/stdio) configuration
264
- - SDK context and client interaction
265
- - Response formatting and error handling
266
-
267
- - **[Container Guide](src/container/)** - Typed dependency injection container
268
- - Understanding DI tokens and registration
269
- - Service lifetimes (singleton, transient, instance)
270
- - Constructor injection patterns
271
- - Testing with mocked dependencies
272
- - Adding new services to the container
273
-
274
- - **[Services Guide](src/services/)** - External service integration patterns
275
- - LLM provider integration (OpenRouter)
276
- - Speech services (TTS/STT with ElevenLabs, Whisper)
277
- - Graph database operations (SurrealDB)
278
- - Creating custom service providers
279
- - Health checks and error handling
280
-
281
- - **[Storage Guide](src/storage/)** - Abstracted persistence layer
282
- - Storage provider implementations
283
- - Multi-tenancy and tenant isolation
284
- - Secure cursor-based pagination
285
- - Batch operations and TTL support
286
- - Provider-specific setup guides
287
-
288
- ### Additional Resources
289
-
290
- - **[AGENTS.md](AGENTS.md)** - Strict development rules for AI agents
291
- - **[CHANGELOG.md](CHANGELOG.md)** - Version history and breaking changes
292
- - **[docs/tree.md](docs/tree.md)** - Complete visual directory structure
293
- - **[docs/publishing-mcp-server-registry.md](docs/publishing-mcp-server-registry.md)** - Publishing guide for MCP Registry
294
-
295
- ## 🧑‍💻 Agent Development Guide
296
-
297
- For a strict set of rules when using this template with an AI agent, please refer to **`AGENTS.md`**. Key principles include:
298
-
299
- - **Logic Throws, Handlers Catch**: Never use `try/catch` in your tool/resource `logic`. Throw an `McpError` instead.
300
- - **Use Elicitation for Missing Input**: If a tool requires user input that wasn't provided, use the `elicitInput` function from the `SdkContext` to ask the user for it.
301
- - **Pass the Context**: Always pass the `RequestContext` object through your call stack.
302
- - **Use the Barrel Exports**: Register new tools and resources only in the `index.ts` barrel files.
303
-
304
- ## ❓ FAQ
305
-
306
- - **Does this work with both STDIO and Streamable HTTP?**
307
- - Yes. Both transports are first-class citizens. Use `bun run dev:stdio` or `bun run dev:http`.
308
- - **Can I deploy this to the edge?**
309
- - Yes. The template is designed for Cloudflare Workers. Run `bun run build:worker` and deploy with Wrangler.
310
- - **Do I have to use OpenTelemetry?**
311
- - No, it is disabled by default. Enable it by setting `OTEL_ENABLED=true` in your `.env` file.
312
- - **How do I publish my server to the MCP Registry?**
313
- - Follow the step-by-step guide in `docs/publishing-mcp-server-registry.md`.
314
-
315
- ## 🤝 Contributing
316
-
317
- Issues and pull requests are welcome! If you plan to contribute, please run the local checks and tests before submitting your PR.
231
+ ## Project structure
232
+
233
+ | Directory | Purpose & Contents | Guide |
234
+ | :-------------------------------------- | :----------------------------------------------------------------------------------- | :----------------------------------- |
235
+ | `src/mcp-server/tools/definitions` | Tool definitions (`*.tool.ts`). Add new capabilities here. | [MCP Guide](src/mcp-server/) |
236
+ | `src/mcp-server/resources/definitions` | Resource definitions (`*.resource.ts`). Add new data sources here. | [MCP Guide](src/mcp-server/) |
237
+ | `src/mcp-server/prompts/definitions` | Prompt definitions (`*.prompt.ts`). Add new prompt templates here. | [MCP Guide](src/mcp-server/) |
238
+ | `src/mcp-server/tasks` | Async task infrastructure (MCP Tasks API, experimental). | [MCP Guide](src/mcp-server/) |
239
+ | `src/mcp-server/transports` | HTTP and STDIO transports, including auth middleware. | [MCP Guide](src/mcp-server/) |
240
+ | `src/storage` | `StorageService` abstraction and provider implementations. | [Storage Guide](src/storage/) |
241
+ | `src/services` | External service integrations (LLM, Speech, Graph) with pluggable providers. | [Services Guide](src/services/) |
242
+ | `src/container` | DI container registrations and tokens. | [Container Guide](src/container/) |
243
+ | `src/utils` | Core utilities for logging, error handling, performance, security, and telemetry. | |
244
+ | `src/config` | Environment variable parsing and validation with Zod. | |
245
+ | `tests/` | Unit and integration tests, mirroring the `src/` directory structure. | |
246
+
247
+ ## Documentation
248
+
249
+ Each module directory has its own README with architecture details and examples.
250
+
251
+ ### Core modules
252
+
253
+ - [MCP Server Guide](src/mcp-server/) Building tools, resources, auth, transports, SDK context, response formatting
254
+ - [Container Guide](src/container/) — DI tokens, registration, service lifetimes, testing with mocks
255
+ - [Services Guide](src/services/) — LLM (OpenRouter), Speech (ElevenLabs, Whisper), Graph, custom providers
256
+ - [Storage Guide](src/storage/) Provider implementations, multi-tenancy, pagination, batch ops, TTL
257
+
258
+ ### Other references
259
+
260
+ - [AGENTS.md](AGENTS.md) Development rules for AI agents
261
+ - [CHANGELOG.md](CHANGELOG.md) Version history and breaking changes
262
+ - [docs/tree.md](docs/tree.md) Visual directory structure
263
+ - [docs/publishing-mcp-server-registry.md](docs/publishing-mcp-server-registry.md) Publishing to MCP Registry
264
+
265
+ ## Agent development guide
266
+
267
+ See `AGENTS.md` for the full rules when using this template with an AI agent. Key principles:
268
+
269
+ - Never use `try/catch` in tool/resource `logic`. Throw `McpError` instead — handlers catch.
270
+ - Use `elicitInput` from `SdkContext` to ask for missing user input.
271
+ - Pass `RequestContext` through the call stack.
272
+ - Import from the defining file, not barrel `index.ts`. Register new tools/resources in `definitions/index.ts`.
273
+
274
+ ## FAQ
275
+
276
+ - **Does this work with both STDIO and Streamable HTTP?** Yes. Use `bun run dev:stdio` or `bun run dev:http`.
277
+ - **Can I deploy this to the edge?** Yes. Run `bun run build:worker` and deploy with Wrangler.
278
+ - **Do I have to use OpenTelemetry?** No, disabled by default. Set `OTEL_ENABLED=true` to enable.
279
+ - **How do I publish my server to the MCP Registry?** See `docs/publishing-mcp-server-registry.md`.
280
+
281
+ ## Contributing
282
+
283
+ Issues and pull requests are welcome. Run checks and tests before submitting:
318
284
 
319
285
  ```sh
320
286
  bun run devcheck
321
- bun test
287
+ bun run test
322
288
  ```
323
289
 
324
- ## 📜 License
290
+ ## License
325
291
 
326
292
  This project is licensed under the Apache 2.0 License. See the [LICENSE](./LICENSE) file for details.
327
293