mcp-ts-template 2.1.8 → 2.2.1
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 +37 -22
- package/dist/index.js +623 -321
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
<div align="center">
|
|
7
7
|
|
|
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
9
|
|
|
10
10
|
</div>
|
|
11
11
|
|
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
## ✨ Features
|
|
15
15
|
|
|
16
16
|
- **Declarative Tools & Resources**: Define capabilities in single, self-contained files. The framework handles registration and execution.
|
|
17
|
+
- **Elicitation Support**: Tools can interactively prompt the user for missing parameters during execution, streamlining user workflows.
|
|
17
18
|
- **Robust Error Handling**: A unified `McpError` system ensures consistent, structured error responses across the server.
|
|
18
19
|
- **Pluggable Authentication**: Secure your server with zero-fuss support for `none`, `jwt`, or `oauth` modes.
|
|
19
20
|
- **Abstracted Storage**: Swap storage backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2`) without changing business logic.
|
|
@@ -30,21 +31,26 @@
|
|
|
30
31
|
### Installation
|
|
31
32
|
|
|
32
33
|
1. **Clone the repository:**
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
git clone https://github.com/cyanheads/mcp-ts-template.git
|
|
37
|
+
```
|
|
38
|
+
|
|
36
39
|
2. **Navigate into the directory:**
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
cd mcp-ts-template
|
|
43
|
+
```
|
|
44
|
+
|
|
40
45
|
3. **Install dependencies:**
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
bun install
|
|
49
|
+
```
|
|
44
50
|
|
|
45
51
|
## 🛠️ Understanding the Template: Tools & Resources
|
|
46
52
|
|
|
47
|
-
This template includes working examples of
|
|
53
|
+
This template includes working examples of tools and resources.
|
|
48
54
|
|
|
49
55
|
### 1. Example Tool: `template_echo_message`
|
|
50
56
|
|
|
@@ -56,7 +62,10 @@ This tool echoes back a message with optional formatting. You can find the full
|
|
|
56
62
|
```ts
|
|
57
63
|
// Located at: src/mcp-server/tools/definitions/template-echo-message.tool.ts
|
|
58
64
|
import { z } from 'zod';
|
|
59
|
-
import type {
|
|
65
|
+
import type {
|
|
66
|
+
SdkContext,
|
|
67
|
+
ToolDefinition,
|
|
68
|
+
} from '@/mcp-server/tools/utils/toolDefinition.js';
|
|
60
69
|
import { withToolAuth } from '@/mcp-server/transports/auth/lib/withAuth.js';
|
|
61
70
|
import { type RequestContext, logger } from '@/utils/index.js';
|
|
62
71
|
|
|
@@ -86,7 +95,8 @@ const OutputSchema = z.object({
|
|
|
86
95
|
// 2. Implement the pure business logic for the tool.
|
|
87
96
|
async function echoToolLogic(
|
|
88
97
|
input: z.infer<typeof InputSchema>,
|
|
89
|
-
|
|
98
|
+
appContext: RequestContext,
|
|
99
|
+
sdkContext: SdkContext,
|
|
90
100
|
): Promise<z.infer<typeof OutputSchema>> {
|
|
91
101
|
// ... logic to format and repeat the message
|
|
92
102
|
const formattedMessage = input.message.toUpperCase(); // simplified for example
|
|
@@ -98,7 +108,7 @@ async function echoToolLogic(
|
|
|
98
108
|
export const echoTool: ToolDefinition<typeof InputSchema, typeof OutputSchema> =
|
|
99
109
|
{
|
|
100
110
|
name: 'template_echo_message', // The official tool name
|
|
101
|
-
title: 'Echo Message',
|
|
111
|
+
title: 'Template Echo Message',
|
|
102
112
|
description:
|
|
103
113
|
'Echoes a message back with optional formatting and repetition.',
|
|
104
114
|
inputSchema: InputSchema,
|
|
@@ -107,7 +117,7 @@ export const echoTool: ToolDefinition<typeof InputSchema, typeof OutputSchema> =
|
|
|
107
117
|
};
|
|
108
118
|
```
|
|
109
119
|
|
|
110
|
-
The `echoTool` is registered in `src/mcp-server/tools/definitions/index.ts`, making it available to the server on startup.
|
|
120
|
+
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`.
|
|
111
121
|
|
|
112
122
|
</details>
|
|
113
123
|
|
|
@@ -219,19 +229,23 @@ All configuration is centralized and validated at startup in `src/config/index.t
|
|
|
219
229
|
- **Run checks and tests**:
|
|
220
230
|
```sh
|
|
221
231
|
bun devcheck # Lints, formats, type-checks, and more
|
|
222
|
-
bun test
|
|
232
|
+
bun test # Runs the test suite
|
|
223
233
|
```
|
|
224
234
|
|
|
225
235
|
### Cloudflare Workers
|
|
226
236
|
|
|
227
237
|
1. **Build the Worker bundle**:
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
238
|
+
|
|
239
|
+
```sh
|
|
240
|
+
bun build:worker
|
|
241
|
+
```
|
|
242
|
+
|
|
231
243
|
2. **Run locally with Wrangler**:
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
244
|
+
|
|
245
|
+
```sh
|
|
246
|
+
bun deploy:dev
|
|
247
|
+
```
|
|
248
|
+
|
|
235
249
|
3. **Deploy to Cloudflare**:
|
|
236
250
|
`sh
|
|
237
251
|
bun deploy:prod
|
|
@@ -256,6 +270,7 @@ bun deploy:prod
|
|
|
256
270
|
For a strict set of rules when using this template with an AI agent, please refer to **`AGENTS.md`**. Key principles include:
|
|
257
271
|
|
|
258
272
|
- **Logic Throws, Handlers Catch**: Never use `try/catch` in your tool/resource `logic`. Throw an `McpError` instead.
|
|
273
|
+
- **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.
|
|
259
274
|
- **Pass the Context**: Always pass the `RequestContext` object through your call stack.
|
|
260
275
|
- **Use the Barrel Exports**: Register new tools and resources only in the `index.ts` barrel files.
|
|
261
276
|
|