@umbraco-cms/mcp-editor 17.6.0-beta.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.
package/README.md ADDED
@@ -0,0 +1,162 @@
1
+ # umbraco-mcp-editor-cms
2
+
3
+ MCP server template for Umbraco add-ons using the @umbraco-cms/mcp-server-sdk.
4
+
5
+ ## Getting Started
6
+
7
+ ### 1. Install Dependencies
8
+
9
+ ```bash
10
+ npm install
11
+ ```
12
+
13
+ On first clone, run `npm run umbraco:bootstrap` to create `demo-site/` from `demo-site-template/`. Then start the CMS with `npm run start:umbraco`.
14
+
15
+ ### 2. Configure Environment
16
+
17
+ Copy `.env.example` to `.env` and fill in your Umbraco connection details:
18
+
19
+ ```bash
20
+ cp .env.example .env
21
+ ```
22
+
23
+ ### 3. Generate API Client (Optional)
24
+
25
+ If you have an OpenAPI spec for your add-on:
26
+
27
+ 1. Update `orval.config.ts` to point to your spec
28
+ 2. Run the generator:
29
+
30
+ ```bash
31
+ npm run generate
32
+ ```
33
+
34
+ ### 4. Build and Test
35
+
36
+ ```bash
37
+ # Build the server
38
+ npm run build
39
+
40
+ # Run tests
41
+ npm test
42
+
43
+ # Test with MCP Inspector
44
+ npm run inspect
45
+ ```
46
+
47
+ ## Project Structure
48
+
49
+ ```
50
+ ├── src/
51
+ │ ├── api/
52
+ │ │ ├── client.ts # Axios client configuration
53
+ │ │ └── generated/ # Orval-generated API code
54
+ │ ├── tools/
55
+ │ │ └── example/ # Example tool collection
56
+ │ │ ├── get/
57
+ │ │ ├── post/
58
+ │ │ └── index.ts
59
+ │ └── index.ts # Server entry point
60
+ ├── scripts/
61
+ │ └── tunnels.sh # Cloudflare tunnels for remote MCP client testing
62
+ ├── umbraco/
63
+ │ └── McpOAuthComposer.cs # OAuth client registration (copy into your Umbraco project)
64
+ ├── __tests__/
65
+ │ └── example/ # Example tests
66
+ ├── package.json
67
+ ├── tsconfig.json
68
+ ├── tsup.config.ts
69
+ ├── jest.config.ts
70
+ ├── orval.config.ts
71
+ └── .env.example
72
+ ```
73
+
74
+ ## Adding Your Own Tools
75
+
76
+ 1. Create a new folder under `src/tools/` for your tool collection
77
+ 2. Create tool files following the example pattern:
78
+ - `get/` for GET operations
79
+ - `post/` for POST operations
80
+ - `put/` for PUT operations
81
+ - `delete/` for DELETE operations
82
+ 3. Create an `index.ts` that exports the collection
83
+ 4. Register the collection in `src/index.ts`
84
+
85
+ ### Tool Pattern Example
86
+
87
+ ```typescript
88
+ import { z } from "zod";
89
+ import {
90
+ withStandardDecorators,
91
+ executeGetApiCall,
92
+ CAPTURE_RAW_HTTP_RESPONSE,
93
+ ToolDefinition,
94
+ } from "@umbraco-cms/mcp-server-sdk";
95
+
96
+ const inputSchema = {
97
+ id: z.string().uuid(),
98
+ };
99
+
100
+ const myTool: ToolDefinition<typeof inputSchema> = {
101
+ name: "my-tool",
102
+ description: "Does something useful",
103
+ inputSchema,
104
+ slices: ["read"],
105
+ annotations: { readOnlyHint: true },
106
+ handler: async ({ id }) => {
107
+ return executeGetApiCall((client) =>
108
+ client.getMyItem(id, CAPTURE_RAW_HTTP_RESPONSE)
109
+ );
110
+ },
111
+ };
112
+
113
+ export default withStandardDecorators(myTool);
114
+ ```
115
+
116
+ ## Testing
117
+
118
+ Tests use Jest with the MCP toolkit's testing helpers:
119
+
120
+ ```typescript
121
+ import {
122
+ setupTestEnvironment,
123
+ createSnapshotResult,
124
+ createMockRequestHandlerExtra,
125
+ } from "@umbraco-cms/mcp-server-sdk/testing";
126
+
127
+ describe("my-tool", () => {
128
+ setupTestEnvironment();
129
+
130
+ it("should do something", async () => {
131
+ const result = await myTool.handler({ id: "..." }, createMockRequestHandlerExtra());
132
+ expect(createSnapshotResult(result)).toMatchSnapshot();
133
+ });
134
+ });
135
+ ```
136
+
137
+ ## Hosted Worker (Cloudflare)
138
+
139
+ `src/worker.ts` is the entry point for the hosted Cloudflare Worker deployment. It wires `umbracoCloudSiteRouting` unconditionally; the library decides per request whether to engage multi-tenant routing by reading `siteRouting.enabled?(env)`.
140
+
141
+ The Cloud preset gates engagement on a single env var:
142
+
143
+ ```toml
144
+ # wrangler.toml
145
+ [vars]
146
+ UMBRACO_CLOUD_ROUTING_ENABLED = "true" # multi-tenant: /at/{alias}/ + per-request URLs
147
+ ```
148
+
149
+ - Set `UMBRACO_CLOUD_ROUTING_ENABLED = "true"` in `wrangler.toml [vars]` to flip the Worker into multi-tenant Cloud mode — no source edit required.
150
+ - Leave it unset (or set to anything else) for single-tenant deployments that honor `UMBRACO_BASE_URL`.
151
+
152
+ Each Cloud project served by a multi-tenant Worker must register an OpenIddict client with id `umbraco-cms-editor-mcp-hosted` (the per-MCP-type identity baked into `worker.ts`).
153
+
154
+ ## Publishing
155
+
156
+ 1. Update `package.json` with your package name and details
157
+ 2. Build: `npm run build`
158
+ 3. Publish: `npm publish`
159
+
160
+ ## License
161
+
162
+ MIT