mcp-ts-template 2.3.5 → 2.3.7
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 +65 -147
- package/dist/index.js +2159 -1924
- package/package.json +21 -21
package/README.md
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<h1>mcp-ts-template</h1>
|
|
3
|
-
<p><b>Production-grade TypeScript template for building Model Context Protocol (MCP) servers. Ships with declarative tools/resources, robust error handling, DI, easy auth, optional OpenTelemetry, and first-class support for both local and edge (Cloudflare Workers) runtimes.</b
|
|
3
|
+
<p><b>Production-grade TypeScript template for building Model Context Protocol (MCP) servers. Ships with declarative tools/resources, robust error handling, DI, easy auth, optional OpenTelemetry, and first-class support for both local and edge (Cloudflare Workers) runtimes.</b>
|
|
4
|
+
<div>5 Tools • 1 Resource • 1 Prompt</div>
|
|
5
|
+
</p>
|
|
4
6
|
</div>
|
|
5
7
|
|
|
6
8
|
<div align="center">
|
|
7
9
|
|
|
8
|
-
[](./CHANGELOG.md) [](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) [](https://modelcontextprotocol.io/) [](./LICENSE) [](https://github.com/cyanheads/mcp-ts-template/issues) [](https://www.typescriptlang.org/) [](https://bun.sh/) [](./coverage/lcov-report/)
|
|
9
11
|
|
|
10
12
|
</div>
|
|
11
13
|
|
|
@@ -24,6 +26,32 @@
|
|
|
24
26
|
- **Rich Built-in Utility Suite**: Helpers for parsing (PDF, YAML, CSV), scheduling, security, and more.
|
|
25
27
|
- **Edge-Ready**: Write code once and run it seamlessly on your local machine or at the edge on Cloudflare Workers.
|
|
26
28
|
|
|
29
|
+
## 🛠️ Included Capabilities
|
|
30
|
+
|
|
31
|
+
This template includes working examples to get you started.
|
|
32
|
+
|
|
33
|
+
### Tools
|
|
34
|
+
|
|
35
|
+
| Tool | Description |
|
|
36
|
+
| :---------------------------------- | :---------------------------------------------------------------- |
|
|
37
|
+
| **`template_echo_message`** | Echoes a message back with optional formatting and repetition. |
|
|
38
|
+
| **`template_cat_fact`** | Fetches a random cat fact from an external API. |
|
|
39
|
+
| **`template_madlibs_elicitation`** | Demonstrates elicitation by asking for words to complete a story. |
|
|
40
|
+
| **`template_code_review_sampling`** | Uses the LLM service to perform a simulated code review. |
|
|
41
|
+
| **`template_image_test`** | Returns a test image as a base64-encoded data URI. |
|
|
42
|
+
|
|
43
|
+
### Resources
|
|
44
|
+
|
|
45
|
+
| Resource | URI | Description |
|
|
46
|
+
| :--------- | :----------------- | :-------------------------------------------- |
|
|
47
|
+
| **`echo`** | `echo://{message}` | A simple resource that echoes back a message. |
|
|
48
|
+
|
|
49
|
+
### Prompts
|
|
50
|
+
|
|
51
|
+
| Prompt | Description |
|
|
52
|
+
| :---------------- | :--------------------------------------------------------------- |
|
|
53
|
+
| **`code-review`** | A structured prompt for guiding an LLM to perform a code review. |
|
|
54
|
+
|
|
27
55
|
## 🚀 Getting Started
|
|
28
56
|
|
|
29
57
|
### MCP Client Settings/Configuration
|
|
@@ -34,10 +62,14 @@ Add the following to your MCP Client configuration file (e.g., `cline_mcp_settin
|
|
|
34
62
|
{
|
|
35
63
|
"mcpServers": {
|
|
36
64
|
"mcp-ts-template": {
|
|
65
|
+
"type": "stdio",
|
|
37
66
|
"command": "bunx",
|
|
38
67
|
"args": ["mcp-ts-template@latest"],
|
|
39
68
|
"env": {
|
|
40
|
-
"
|
|
69
|
+
"MCP_TRANSPORT_TYPE": "stdio",
|
|
70
|
+
"MCP_LOG_LEVEL": "info",
|
|
71
|
+
"STORAGE_PROVIDER_TYPE": "filesystem",
|
|
72
|
+
"STORAGE_FILESYSTEM_PATH": "/path/to/your/storage"
|
|
41
73
|
}
|
|
42
74
|
}
|
|
43
75
|
}
|
|
@@ -68,151 +100,25 @@ cd mcp-ts-template
|
|
|
68
100
|
bun install
|
|
69
101
|
```
|
|
70
102
|
|
|
71
|
-
##
|
|
72
|
-
|
|
73
|
-
This template includes working examples of tools and resources.
|
|
74
|
-
|
|
75
|
-
### 1. Example Tool: `template_echo_message`
|
|
76
|
-
|
|
77
|
-
This tool echoes back a message with optional formatting. You can find the full source at `src/mcp-server/tools/definitions/template-echo-message.tool.ts`.
|
|
78
|
-
|
|
79
|
-
<details>
|
|
80
|
-
<summary>Click to see the `echoTool` definition structure</summary>
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
// Located at: src/mcp-server/tools/definitions/template-echo-message.tool.ts
|
|
84
|
-
import { z } from 'zod';
|
|
85
|
-
import type {
|
|
86
|
-
SdkContext,
|
|
87
|
-
ToolDefinition,
|
|
88
|
-
} from '@/mcp-server/tools/utils/toolDefinition.js';
|
|
89
|
-
import { withToolAuth } from '@/mcp-server/transports/auth/lib/withAuth.js';
|
|
90
|
-
import { type RequestContext, logger } from '@/utils/index.js';
|
|
91
|
-
|
|
92
|
-
// 1. Define Input and Output Schemas with Zod for validation.
|
|
93
|
-
const InputSchema = z.object({
|
|
94
|
-
message: z.string().min(1).describe('The message to echo back.'),
|
|
95
|
-
mode: z
|
|
96
|
-
.enum(['standard', 'uppercase', 'lowercase'])
|
|
97
|
-
.default('standard')
|
|
98
|
-
.describe('Formatting mode.'),
|
|
99
|
-
repeat: z
|
|
100
|
-
.number()
|
|
101
|
-
.int()
|
|
102
|
-
.min(1)
|
|
103
|
-
.max(5)
|
|
104
|
-
.default(1)
|
|
105
|
-
.describe('Number of times to repeat the message.'),
|
|
106
|
-
});
|
|
107
|
-
|
|
108
|
-
const OutputSchema = z.object({
|
|
109
|
-
repeatedMessage: z
|
|
110
|
-
.string()
|
|
111
|
-
.describe('The final, formatted, and repeated message.'),
|
|
112
|
-
// ... other fields from the actual file
|
|
113
|
-
});
|
|
114
|
-
|
|
115
|
-
// 2. Implement the pure business logic for the tool.
|
|
116
|
-
async function echoToolLogic(
|
|
117
|
-
input: z.infer<typeof InputSchema>,
|
|
118
|
-
appContext: RequestContext,
|
|
119
|
-
sdkContext: SdkContext,
|
|
120
|
-
): Promise<z.infer<typeof OutputSchema>> {
|
|
121
|
-
// ... logic to format and repeat the message
|
|
122
|
-
const formattedMessage = input.message.toUpperCase(); // simplified for example
|
|
123
|
-
const repeatedMessage = Array(input.repeat).fill(formattedMessage).join(' ');
|
|
124
|
-
return { repeatedMessage };
|
|
125
|
-
}
|
|
126
|
-
|
|
127
|
-
// 3. Assemble the final Tool Definition.
|
|
128
|
-
export const echoTool: ToolDefinition<typeof InputSchema, typeof OutputSchema> =
|
|
129
|
-
{
|
|
130
|
-
name: 'template_echo_message', // The official tool name
|
|
131
|
-
title: 'Template Echo Message',
|
|
132
|
-
description:
|
|
133
|
-
'Echoes a message back with optional formatting and repetition.',
|
|
134
|
-
inputSchema: InputSchema,
|
|
135
|
-
outputSchema: OutputSchema,
|
|
136
|
-
logic: withToolAuth(['tool:echo:read'], echoToolLogic), // Secure the tool
|
|
137
|
-
};
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
The `echoTool` is registered in `src/mcp-server/tools/definitions/index.ts`, making it available to the server on startup. For an example of how to use the new elicitation feature, see `template_madlibs_elicitation.tool.ts`.
|
|
141
|
-
|
|
142
|
-
</details>
|
|
143
|
-
|
|
144
|
-
### 2. Example Resource: `echo-resource`
|
|
145
|
-
|
|
146
|
-
This resource provides a simple echo response via a URI. The source is located at `src/mcp-server/resources/definitions/echo.resource.ts`.
|
|
147
|
-
|
|
148
|
-
<details>
|
|
149
|
-
<summary>Click to see the `echoResourceDefinition` structure</summary>
|
|
150
|
-
|
|
151
|
-
```ts
|
|
152
|
-
// Located at: src/mcp-server/resources/definitions/echo.resource.ts
|
|
153
|
-
import { z } from 'zod';
|
|
154
|
-
import type { ResourceDefinition } from '@/mcp-server/resources/utils/resourceDefinition.js';
|
|
155
|
-
import { withResourceAuth } from '@/mcp-server/transports/auth/lib/withAuth.js';
|
|
156
|
-
import { type RequestContext, logger } from '@/utils/index.js';
|
|
157
|
-
|
|
158
|
-
// 1. Define Parameter and Output Schemas.
|
|
159
|
-
const ParamsSchema = z.object({
|
|
160
|
-
message: z.string().optional().describe('Message to echo from the URI.'),
|
|
161
|
-
});
|
|
162
|
-
|
|
163
|
-
const OutputSchema = z.object({
|
|
164
|
-
message: z.string().describe('The echoed message.'),
|
|
165
|
-
timestamp: z.string().datetime().describe('Timestamp of the response.'),
|
|
166
|
-
requestUri: z.string().url().describe('The original request URI.'),
|
|
167
|
-
});
|
|
168
|
-
|
|
169
|
-
// 2. Implement the pure read logic for the resource.
|
|
170
|
-
function echoLogic(
|
|
171
|
-
uri: URL,
|
|
172
|
-
params: z.infer<typeof ParamsSchema>,
|
|
173
|
-
context: RequestContext,
|
|
174
|
-
): z.infer<typeof OutputSchema> {
|
|
175
|
-
const messageToEcho = params.message || uri.hostname || 'Default echo';
|
|
176
|
-
return {
|
|
177
|
-
message: messageToEcho,
|
|
178
|
-
timestamp: new Date().toISOString(),
|
|
179
|
-
requestUri: uri.href,
|
|
180
|
-
};
|
|
181
|
-
}
|
|
182
|
-
|
|
183
|
-
// 3. Assemble the final Resource Definition.
|
|
184
|
-
export const echoResourceDefinition: ResourceDefinition<
|
|
185
|
-
typeof ParamsSchema,
|
|
186
|
-
typeof OutputSchema
|
|
187
|
-
> = {
|
|
188
|
-
name: 'echo-resource', // The official resource name
|
|
189
|
-
title: 'Echo Message Resource',
|
|
190
|
-
description: 'A simple echo resource that returns a message.',
|
|
191
|
-
uriTemplate: 'echo://{message}',
|
|
192
|
-
paramsSchema: ParamsSchema,
|
|
193
|
-
outputSchema: OutputSchema,
|
|
194
|
-
logic: withResourceAuth(['resource:echo:read'], echoLogic), // Secure the resource
|
|
195
|
-
};
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
Like the tool, `echoResourceDefinition` is registered in `src/mcp-server/resources/definitions/index.ts`.
|
|
199
|
-
|
|
200
|
-
</details>
|
|
201
|
-
|
|
202
|
-
## ⚙️ Core Concepts
|
|
203
|
-
|
|
204
|
-
### Configuration
|
|
103
|
+
## ⚙️ Configuration
|
|
205
104
|
|
|
206
105
|
All configuration is centralized and validated at startup in `src/config/index.ts`. Key environment variables in your `.env` file include:
|
|
207
106
|
|
|
208
|
-
| Variable
|
|
209
|
-
|
|
|
210
|
-
| `MCP_TRANSPORT_TYPE`
|
|
211
|
-
| `MCP_HTTP_PORT`
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
214
|
-
| `
|
|
215
|
-
| `
|
|
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)` |
|
|
216
122
|
|
|
217
123
|
### Authentication & Authorization
|
|
218
124
|
|
|
@@ -267,9 +173,12 @@ bun deploy:dev
|
|
|
267
173
|
```
|
|
268
174
|
|
|
269
175
|
3. **Deploy to Cloudflare**:
|
|
270
|
-
|
|
176
|
+
|
|
177
|
+
```sh
|
|
271
178
|
bun deploy:prod
|
|
272
|
-
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
> **Note**: The `wrangler.toml` file is pre-configured to enable `nodejs_compat` for best results.
|
|
273
182
|
|
|
274
183
|
## 📂 Project Structure
|
|
275
184
|
|
|
@@ -317,3 +226,12 @@ bun test
|
|
|
317
226
|
## 📜 License
|
|
318
227
|
|
|
319
228
|
This project is licensed under the Apache 2.0 License. See the [LICENSE](./LICENSE) file for details.
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
<div align="center">
|
|
233
|
+
<p>
|
|
234
|
+
<a href="https://github.com/sponsors/cyanheads">Sponsor this project</a> •
|
|
235
|
+
<a href="https://www.buymeacoffee.com/cyanheads">Buy me a coffee</a>
|
|
236
|
+
</p>
|
|
237
|
+
</div>
|