@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 +162 -0
- package/dist/collections.js +7492 -0
- package/dist/collections.js.map +1 -0
- package/dist/index.js +7787 -0
- package/dist/index.js.map +1 -0
- package/package.json +80 -0
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
|