@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-4
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.
Potentially problematic release.
This version of @ema.co/mcp-toolkit might be problematic. Click here for more details.
- package/README.md +10 -2
- package/dist/mcp/handlers/action/index.js +3 -18
- package/dist/mcp/handlers/data/index.js +385 -41
- package/dist/mcp/handlers/data/templates.js +107 -0
- package/dist/mcp/handlers/deprecation.js +50 -0
- package/dist/mcp/handlers/env/index.js +8 -4
- package/dist/mcp/handlers/knowledge/index.js +44 -237
- package/dist/mcp/handlers/persona/create.js +47 -18
- package/dist/mcp/handlers/persona/index.js +14 -11
- package/dist/mcp/handlers/persona/update.js +4 -2
- package/dist/mcp/handlers/persona/version.js +234 -0
- package/dist/mcp/handlers/sync/index.js +3 -18
- package/dist/mcp/handlers/template/index.js +75 -10
- package/dist/mcp/handlers/workflow/analyze.js +171 -0
- package/dist/mcp/handlers/workflow/compare.js +70 -0
- package/dist/mcp/handlers/workflow/deploy.js +73 -0
- package/dist/mcp/handlers/workflow/generate.js +350 -0
- package/dist/mcp/handlers/workflow/index.js +294 -0
- package/dist/mcp/handlers/workflow/modify.js +456 -0
- package/dist/mcp/handlers/workflow/optimize.js +136 -0
- package/dist/mcp/handlers/workflow/types.js +4 -0
- package/dist/mcp/handlers/workflow/utils.js +30 -0
- package/dist/mcp/handlers-consolidated.js +73 -2696
- package/dist/mcp/prompts.js +83 -43
- package/dist/mcp/resources.js +382 -57
- package/dist/mcp/server.js +199 -391
- package/dist/mcp/{tools-v2.js → tools.js} +20 -54
- package/dist/mcp/workflow-operations.js +2 -2
- package/dist/sdk/client-adapter.js +267 -32
- package/dist/sdk/client.js +45 -16
- package/dist/sdk/ema-client.js +183 -0
- package/dist/sdk/generated/deprecated-actions.js +171 -0
- package/dist/sdk/generated/template-fallbacks.js +123 -0
- package/dist/sdk/guidance.js +65 -11
- package/dist/sdk/index.js +3 -1
- package/dist/sdk/knowledge.js +139 -86
- package/dist/sdk/workflow-intent.js +27 -0
- package/dist/sdk/workflow-transformer.js +0 -342
- package/docs/mcp-tools-guide.md +37 -45
- package/package.json +10 -4
- package/dist/mcp/handlers/persona/analyze.js +0 -275
- package/dist/mcp/handlers/persona/compare.js +0 -32
- package/dist/mcp/tools-consolidated.js +0 -875
- package/dist/mcp/tools-legacy.js +0 -736
- package/docs/CODEBASE-ANALYSIS-2026-01-23.md +0 -936
- package/docs/CODEBASE-ANALYSIS-PRIORITIZED.md +0 -774
- package/docs/api-contracts.md +0 -216
- package/docs/auto-builder-analysis.md +0 -271
- package/docs/blog/mcp-tool-design-lessons.md +0 -309
- package/docs/data-architecture.md +0 -166
- package/docs/demos/ap-invoice-generation.md +0 -347
- package/docs/demos/ap-invoice-processing.md +0 -271
- package/docs/ema-auto-builder-guide.html +0 -394
- package/docs/lessons-learned.md +0 -209
- package/docs/llm-native-workflow-design.md +0 -252
- package/docs/local-generation.md +0 -508
- package/docs/mcp-flow-diagram.md +0 -135
- package/docs/migration/action-composition-migration.md +0 -270
- package/docs/naming-conventions.md +0 -278
- package/docs/proposals/HANDOFF-tool-restructure.md +0 -526
- package/docs/proposals/action-composition.md +0 -490
- package/docs/proposals/explicit-method-restructure.md +0 -328
- package/docs/proposals/mcp-tool-restructure-2026-01.md +0 -366
- package/docs/proposals/self-contained-guidance.md +0 -427
- package/docs/proto-sdk-generation.md +0 -242
- package/docs/release-impact.md +0 -102
- package/docs/release-process.md +0 -157
- package/docs/staging.RULE.md +0 -142
- package/docs/test-persona-creation.md +0 -196
- package/docs/tool-consolidation-v2.md +0 -225
- package/docs/tool-response-standards.md +0 -256
- package/resources/demo-kits/README.md +0 -175
- package/resources/demo-kits/finance-ap/manifest.json +0 -150
- package/resources/demo-kits/tags.json +0 -91
- package/resources/docs/getting-started.md +0 -97
- package/resources/templates/auto-builder-rules.md +0 -224
- package/resources/templates/chat-ai/README.md +0 -119
- package/resources/templates/chat-ai/persona-config.json +0 -111
- package/resources/templates/dashboard-ai/README.md +0 -156
- package/resources/templates/dashboard-ai/persona-config.json +0 -180
- package/resources/templates/demo-scenarios/README.md +0 -63
- package/resources/templates/demo-scenarios/test-published-package.md +0 -116
- package/resources/templates/document-gen-ai/README.md +0 -132
- package/resources/templates/document-gen-ai/persona-config.json +0 -316
- package/resources/templates/voice-ai/README.md +0 -123
- package/resources/templates/voice-ai/persona-config.json +0 -74
- package/resources/templates/voice-ai/workflow-prompt.md +0 -121
|
@@ -1,328 +0,0 @@
|
|
|
1
|
-
# MCP Tool Restructure: Explicit Methods
|
|
2
|
-
|
|
3
|
-
> **Status**: APPROVED - Ready for implementation
|
|
4
|
-
> **Date**: 2026-01-19
|
|
5
|
-
> **Branch**: `feat/mcp-tool-restructure`
|
|
6
|
-
|
|
7
|
-
## Summary
|
|
8
|
-
|
|
9
|
-
Restructure all MCP tool operations to use explicit `method` parameters instead of inferring operations from the presence of other parameters.
|
|
10
|
-
|
|
11
|
-
## Motivation
|
|
12
|
-
|
|
13
|
-
### Current Problem
|
|
14
|
-
|
|
15
|
-
```typescript
|
|
16
|
-
// What operation is this?
|
|
17
|
-
persona(id="abc", analyze=true) // analyze? get with flag?
|
|
18
|
-
persona(id="abc", delete=true) // delete? get with flag?
|
|
19
|
-
persona(id="abc") // get? list filtered?
|
|
20
|
-
persona(data={upload: "path"}) // upload inferred from param presence
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
The current design:
|
|
24
|
-
1. **Conflates LLM intent with MCP dispatch** - MCP infers what operation to perform
|
|
25
|
-
2. **Ambiguous** - Multiple params present = unclear which operation
|
|
26
|
-
3. **Hard to validate** - Can't validate required params without knowing the operation
|
|
27
|
-
4. **Inconsistent** - Some operations explicit (`create={}`) others implicit (`analyze=true`)
|
|
28
|
-
|
|
29
|
-
### Principle
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
LLM = interprets user intent, chooses operation
|
|
33
|
-
MCP = executes structured request
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
The LLM should explicitly declare what operation it wants. MCP should not guess.
|
|
37
|
-
|
|
38
|
-
## Design
|
|
39
|
-
|
|
40
|
-
### Persona Tool
|
|
41
|
-
|
|
42
|
-
All operations require explicit `method` parameter.
|
|
43
|
-
|
|
44
|
-
```typescript
|
|
45
|
-
// Query
|
|
46
|
-
persona(method="list")
|
|
47
|
-
persona(method="list", type="voice", status="active")
|
|
48
|
-
persona(method="get", id="abc")
|
|
49
|
-
|
|
50
|
-
// Mutate
|
|
51
|
-
persona(method="create", name="Bot", type="voice")
|
|
52
|
-
persona(method="create", name="Bot", from="template-id") // from template
|
|
53
|
-
persona(method="create", name="Bot", from="persona-id") // clone
|
|
54
|
-
persona(method="update", id="abc", config={...})
|
|
55
|
-
persona(method="update", id="abc", input="add HITL")
|
|
56
|
-
persona(method="delete", id="abc", confirm=true)
|
|
57
|
-
|
|
58
|
-
// Analyze
|
|
59
|
-
persona(method="analyze", id="abc")
|
|
60
|
-
|
|
61
|
-
// Sanitize
|
|
62
|
-
persona(method="sanitize", id="abc") // preview
|
|
63
|
-
persona(method="sanitize", id="abc", examples=[...], apply=true) // apply
|
|
64
|
-
|
|
65
|
-
// History
|
|
66
|
-
persona(method="snapshot", id="abc", message="before change")
|
|
67
|
-
persona(method="history", id="abc")
|
|
68
|
-
persona(method="restore", id="abc", version="v3")
|
|
69
|
-
|
|
70
|
-
// Compare
|
|
71
|
-
persona(method="compare", id="abc", to="def")
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### Data Sub-Resource
|
|
75
|
-
|
|
76
|
-
Data operations also require explicit `method` inside the `data` object.
|
|
77
|
-
|
|
78
|
-
```typescript
|
|
79
|
-
// Discovery (MCP provides info to LLM)
|
|
80
|
-
persona(id="abc", data={method:"list"})
|
|
81
|
-
persona(id="abc", data={method:"schema"}) // Get input schema for LLM to generate content
|
|
82
|
-
|
|
83
|
-
// Create (LLM provides content)
|
|
84
|
-
persona(id="abc", data={method:"upload", path:"/file.pdf"})
|
|
85
|
-
persona(id="abc", data={method:"upload", content:[{name:"doc.md", document:"..."}]})
|
|
86
|
-
|
|
87
|
-
// Copy (deterministic operation)
|
|
88
|
-
persona(id="abc", data={method:"copy", from:"source-id"})
|
|
89
|
-
persona(id="abc", data={method:"copy", from:"source-id", sanitize:true})
|
|
90
|
-
|
|
91
|
-
// Manage
|
|
92
|
-
persona(id="abc", data={method:"delete", id:"item-123"})
|
|
93
|
-
persona(id="abc", data={method:"embed", enabled:true})
|
|
94
|
-
persona(id="abc", data={method:"search", query:"pricing"})
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
### Catalog Tool
|
|
98
|
-
|
|
99
|
-
Already has `type` as required discriminator. Add `method` for consistency:
|
|
100
|
-
|
|
101
|
-
```typescript
|
|
102
|
-
catalog(method="list", type="actions")
|
|
103
|
-
catalog(method="get", type="actions", id="knowledge_search")
|
|
104
|
-
catalog(method="search", type="actions", query="email")
|
|
105
|
-
catalog(method="recommend", type="actions", for="send email with approval")
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
### Sync Tool
|
|
109
|
-
|
|
110
|
-
```typescript
|
|
111
|
-
sync(method="preview", persona="abc", from="staging", to="prod")
|
|
112
|
-
sync(method="execute", persona="abc", from="staging", to="prod")
|
|
113
|
-
sync(method="status")
|
|
114
|
-
sync(method="status", persona="abc")
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
## Schema
|
|
118
|
-
|
|
119
|
-
### Persona Tool Schema
|
|
120
|
-
|
|
121
|
-
```typescript
|
|
122
|
-
{
|
|
123
|
-
name: "persona",
|
|
124
|
-
inputSchema: {
|
|
125
|
-
type: "object",
|
|
126
|
-
properties: {
|
|
127
|
-
// Required method
|
|
128
|
-
method: {
|
|
129
|
-
type: "string",
|
|
130
|
-
enum: ["list", "get", "create", "update", "delete",
|
|
131
|
-
"analyze", "sanitize", "snapshot", "history", "restore", "compare"],
|
|
132
|
-
description: "Operation to perform (required)"
|
|
133
|
-
},
|
|
134
|
-
|
|
135
|
-
// Identity
|
|
136
|
-
id: { type: "string", description: "Persona ID or name" },
|
|
137
|
-
|
|
138
|
-
// Filters (for list)
|
|
139
|
-
type: { type: "string", enum: ["voice", "chat", "dashboard"] },
|
|
140
|
-
status: { type: "string", enum: ["active", "inactive", "disabled"] },
|
|
141
|
-
query: { type: "string", description: "Search by name" },
|
|
142
|
-
|
|
143
|
-
// Create params
|
|
144
|
-
name: { type: "string", description: "Name (for method=create)" },
|
|
145
|
-
from: { type: "string", description: "Template/persona ID to clone from" },
|
|
146
|
-
|
|
147
|
-
// Update params
|
|
148
|
-
config: { type: "object", description: "Proto config" },
|
|
149
|
-
input: { type: "string", description: "Natural language instruction" },
|
|
150
|
-
workflow_spec: { type: "object", description: "WorkflowSpec (agent-built)" },
|
|
151
|
-
|
|
152
|
-
// Delete params
|
|
153
|
-
confirm: { type: "boolean", description: "Confirm deletion" },
|
|
154
|
-
|
|
155
|
-
// Sanitize params
|
|
156
|
-
examples: { type: "array", items: { type: "string" } },
|
|
157
|
-
apply: { type: "boolean", description: "Apply sanitization" },
|
|
158
|
-
|
|
159
|
-
// Snapshot params
|
|
160
|
-
message: { type: "string", description: "Snapshot message" },
|
|
161
|
-
|
|
162
|
-
// Restore params
|
|
163
|
-
version: { type: "string", description: "Version to restore" },
|
|
164
|
-
|
|
165
|
-
// Compare params
|
|
166
|
-
to: { type: "string", description: "Compare target ID" },
|
|
167
|
-
|
|
168
|
-
// Options
|
|
169
|
-
include_workflow: { type: "boolean" },
|
|
170
|
-
preview: { type: "boolean" },
|
|
171
|
-
env: { type: "string" },
|
|
172
|
-
|
|
173
|
-
// Data sub-resource
|
|
174
|
-
data: {
|
|
175
|
-
type: "object",
|
|
176
|
-
properties: {
|
|
177
|
-
method: {
|
|
178
|
-
type: "string",
|
|
179
|
-
enum: ["list", "schema", "upload", "copy", "delete", "embed", "search"],
|
|
180
|
-
description: "Data operation (required)"
|
|
181
|
-
},
|
|
182
|
-
from: { type: "string", description: "Source persona (for copy)" },
|
|
183
|
-
sanitize: { type: "boolean", description: "Mask PII (for copy)" },
|
|
184
|
-
path: { type: "string", description: "File path (for upload)" },
|
|
185
|
-
content: { type: "array", items: { type: "object" }, description: "Content array (for upload)" },
|
|
186
|
-
id: { type: "string", description: "Item ID (for delete)" },
|
|
187
|
-
enabled: { type: "boolean", description: "Enable/disable (for embed)" },
|
|
188
|
-
query: { type: "string", description: "Search query" },
|
|
189
|
-
},
|
|
190
|
-
required: ["method"],
|
|
191
|
-
},
|
|
192
|
-
},
|
|
193
|
-
required: ["method"],
|
|
194
|
-
}
|
|
195
|
-
}
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
## Migration
|
|
199
|
-
|
|
200
|
-
### Breaking Changes
|
|
201
|
-
|
|
202
|
-
| Old | New |
|
|
203
|
-
|-----|-----|
|
|
204
|
-
| `persona()` | `persona(method="list")` |
|
|
205
|
-
| `persona(id="abc")` | `persona(method="get", id="abc")` |
|
|
206
|
-
| `persona(analyze=true, id="abc")` | `persona(method="analyze", id="abc")` |
|
|
207
|
-
| `persona(delete=true, id="abc")` | `persona(method="delete", id="abc", confirm=true)` |
|
|
208
|
-
| `persona(sanitize=true, id="abc")` | `persona(method="sanitize", id="abc")` |
|
|
209
|
-
| `persona(data={upload:"path"})` | `persona(id="abc", data={method:"upload", path:"..."})` |
|
|
210
|
-
| `persona(data={dashboard_clone:"src"})` | `persona(id="abc", data={method:"copy", from:"src"})` |
|
|
211
|
-
| `persona(data={dashboard_generate:5})` | REMOVED - LLM generates, uses `data={method:"upload", content:[...]}` |
|
|
212
|
-
|
|
213
|
-
### Removed Parameters
|
|
214
|
-
|
|
215
|
-
| Removed | Replacement |
|
|
216
|
-
|---------|-------------|
|
|
217
|
-
| `analyze: boolean` | `method="analyze"` |
|
|
218
|
-
| `delete: boolean` | `method="delete"` |
|
|
219
|
-
| `sanitize: boolean` | `method="sanitize"` |
|
|
220
|
-
| `sanitize_examples` | `examples` (with method="sanitize") |
|
|
221
|
-
| `snapshot: string` | `message` (with method="snapshot") |
|
|
222
|
-
| `history: boolean` | `method="history"` |
|
|
223
|
-
| `restore: string` | `version` (with method="restore") |
|
|
224
|
-
| `compare: string` | `to` (with method="compare") |
|
|
225
|
-
| `dashboard_clone` | `data={method:"copy", from:"..."}` |
|
|
226
|
-
| `dashboard_generate` | `data={method:"upload", content:[...]}` |
|
|
227
|
-
| `generate` (for data) | REMOVED - LLM provides content via upload |
|
|
228
|
-
| `template` (for data) | REMOVED - LLM decides content type |
|
|
229
|
-
|
|
230
|
-
## Handler Dispatch
|
|
231
|
-
|
|
232
|
-
```typescript
|
|
233
|
-
export async function handlePersona(args: Args, client: EmaClient): Promise<HandlerResult> {
|
|
234
|
-
// Data sub-resource
|
|
235
|
-
if (args.data) {
|
|
236
|
-
return handlePersonaData(args.id, args.data, client);
|
|
237
|
-
}
|
|
238
|
-
|
|
239
|
-
// Main dispatch
|
|
240
|
-
switch (args.method) {
|
|
241
|
-
case "list": return handleList(args, client);
|
|
242
|
-
case "get": return handleGet(args.id, args, client);
|
|
243
|
-
case "create": return handleCreate(args, client);
|
|
244
|
-
case "update": return handleUpdate(args, client);
|
|
245
|
-
case "delete": return handleDelete(args.id, args.confirm, client);
|
|
246
|
-
case "analyze": return handleAnalyze(args.id, args, client);
|
|
247
|
-
case "sanitize": return handleSanitize(args, client);
|
|
248
|
-
case "snapshot": return handleSnapshot(args.id, args.message, client);
|
|
249
|
-
case "history": return handleHistory(args.id, client);
|
|
250
|
-
case "restore": return handleRestore(args.id, args.version, client);
|
|
251
|
-
case "compare": return handleCompare(args.id, args.to, client);
|
|
252
|
-
default:
|
|
253
|
-
return { error: `Unknown method: ${args.method}`, hint: "Valid: list, get, create, update, delete, analyze, sanitize, snapshot, history, restore, compare" };
|
|
254
|
-
}
|
|
255
|
-
}
|
|
256
|
-
|
|
257
|
-
function handlePersonaData(personaId: string, data: DataArgs, client: EmaClient): Promise<HandlerResult> {
|
|
258
|
-
switch (data.method) {
|
|
259
|
-
case "list": return handleDataList(personaId, client);
|
|
260
|
-
case "schema": return handleDataSchema(personaId, client);
|
|
261
|
-
case "upload": return handleDataUpload(personaId, data, client);
|
|
262
|
-
case "copy": return handleDataCopy(personaId, data, client);
|
|
263
|
-
case "delete": return handleDataDelete(personaId, data.id, client);
|
|
264
|
-
case "embed": return handleDataEmbed(personaId, data.enabled, client);
|
|
265
|
-
case "search": return handleDataSearch(personaId, data.query, client);
|
|
266
|
-
default:
|
|
267
|
-
return { error: `Unknown data method: ${data.method}`, hint: "Valid: list, schema, upload, copy, delete, embed, search" };
|
|
268
|
-
}
|
|
269
|
-
}
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
## LLM/MCP Responsibility Split
|
|
273
|
-
|
|
274
|
-
| Responsibility | LLM | MCP |
|
|
275
|
-
|----------------|-----|-----|
|
|
276
|
-
| Interpret user intent | ✅ | |
|
|
277
|
-
| Choose operation (method) | ✅ | |
|
|
278
|
-
| Generate content | ✅ | |
|
|
279
|
-
| Decide content type | ✅ | |
|
|
280
|
-
| Provide schema | | ✅ |
|
|
281
|
-
| Execute API calls | | ✅ |
|
|
282
|
-
| Apply sanitization | | ✅ |
|
|
283
|
-
| Return structured results | | ✅ |
|
|
284
|
-
|
|
285
|
-
## Example Flow
|
|
286
|
-
|
|
287
|
-
```
|
|
288
|
-
User: "Add 5 test contracts to my Contract Analyzer"
|
|
289
|
-
│
|
|
290
|
-
▼
|
|
291
|
-
┌─────────────────────────────────────────────────────┐
|
|
292
|
-
│ LLM │
|
|
293
|
-
│ │
|
|
294
|
-
│ 1. Understands: user wants test data for dashboard │
|
|
295
|
-
│ 2. Calls: persona(method="get", id="Contract...") │
|
|
296
|
-
│ 3. Sees: dashboard type, gets ID │
|
|
297
|
-
│ 4. Calls: persona(id="abc", data={method:"schema"}) │
|
|
298
|
-
│ 5. Sees: columns = [document, title, date, value] │
|
|
299
|
-
│ 6. Generates: 5 realistic contracts internally │
|
|
300
|
-
│ 7. Calls: persona(id="abc", data={ │
|
|
301
|
-
│ method:"upload", │
|
|
302
|
-
│ content:[ │
|
|
303
|
-
│ {document:{...}, title:"...", ...}, │
|
|
304
|
-
│ ... │
|
|
305
|
-
│ ] │
|
|
306
|
-
│ }) │
|
|
307
|
-
└─────────────────────────────────────────────────────┘
|
|
308
|
-
│
|
|
309
|
-
▼
|
|
310
|
-
┌─────────────────────────────────────────────────────┐
|
|
311
|
-
│ MCP │
|
|
312
|
-
│ │
|
|
313
|
-
│ 1. Validates: method="upload", content provided │
|
|
314
|
-
│ 2. For each item in content: │
|
|
315
|
-
│ - Formats for API │
|
|
316
|
-
│ - Calls uploadAndRunDashboardRow() │
|
|
317
|
-
│ 3. Returns: {uploaded: 5, rows: [...]} │
|
|
318
|
-
└─────────────────────────────────────────────────────┘
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
## Approval
|
|
322
|
-
|
|
323
|
-
- [x] Design reviewed
|
|
324
|
-
- [x] Breaking changes documented
|
|
325
|
-
- [x] Migration path clear
|
|
326
|
-
- [ ] Implementation planned
|
|
327
|
-
- [ ] Tests updated
|
|
328
|
-
- [ ] Documentation updated
|
|
@@ -1,366 +0,0 @@
|
|
|
1
|
-
# Proposal: MCP Tool Structure Refactoring
|
|
2
|
-
|
|
3
|
-
**Date**: 2026-01-17
|
|
4
|
-
**Status**: Draft
|
|
5
|
-
**Author**: AI Assistant (with user guidance)
|
|
6
|
-
|
|
7
|
-
## Executive Summary
|
|
8
|
-
|
|
9
|
-
Refactor the Ema MCP server from 7 mode-based tools with 30+ parameters each to ~32 focused tools following industry-standard `{resource}_{action}` naming. This aligns with the MCP specification, popular MCP servers (Playwright, Firecrawl, Supabase), and improves LLM discoverability.
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## Problem Statement
|
|
14
|
-
|
|
15
|
-
### Current State
|
|
16
|
-
|
|
17
|
-
The Ema MCP server consolidates ~45 legacy tools into 7 "super tools" using a `mode` parameter:
|
|
18
|
-
|
|
19
|
-
```typescript
|
|
20
|
-
// Current: Mode-based approach
|
|
21
|
-
persona(mode="list")
|
|
22
|
-
persona(mode="get", id="abc")
|
|
23
|
-
persona(mode="create", name="Bot", type="voice", input="...", preview=false)
|
|
24
|
-
persona(mode="analyze", id="abc", fix=true, include=["workflow", "config"])
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
### Issues
|
|
28
|
-
|
|
29
|
-
| Issue | Impact |
|
|
30
|
-
|-------|--------|
|
|
31
|
-
| **30+ params per tool** | LLMs see all params even when irrelevant to the mode |
|
|
32
|
-
| **Mode confusion** | "Did I need `mode='get'` or just pass `id`?" |
|
|
33
|
-
| **Inconsistent patterns** | Some tools use `mode`, others use flags (`all=true`) |
|
|
34
|
-
| **Overlapping functionality** | `reference(type="actions")` duplicates `action(all=true)` |
|
|
35
|
-
| **3 deprecated tools visible** | `workflow`, `knowledge`, `demo` add noise |
|
|
36
|
-
|
|
37
|
-
### Evidence
|
|
38
|
-
|
|
39
|
-
- **Playwright MCP**: Uses `browser_click`, `browser_navigate`, `browser_type` (15+ focused tools)
|
|
40
|
-
- **Firecrawl MCP**: Uses `firecrawl_scrape`, `firecrawl_crawl`, `firecrawl_search` (6 tools)
|
|
41
|
-
- **Filesystem MCP**: Uses `read_file`, `write_file`, `list_directory` (10+ tools)
|
|
42
|
-
- **MCP Spec**: Explicitly allows `admin.tools.list` style naming; examples use `get_weather`
|
|
43
|
-
|
|
44
|
-
---
|
|
45
|
-
|
|
46
|
-
## Proposed Solution
|
|
47
|
-
|
|
48
|
-
### Tool Naming Convention
|
|
49
|
-
|
|
50
|
-
**Pattern**: `{resource}_{action}` (snake_case)
|
|
51
|
-
|
|
52
|
-
```typescript
|
|
53
|
-
// Proposed: Action-based approach
|
|
54
|
-
persona_list()
|
|
55
|
-
persona_get(id="abc")
|
|
56
|
-
persona_create(name="Bot", type="voice", input="...")
|
|
57
|
-
persona_analyze(id="abc", fix=true)
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
### Why This Pattern
|
|
61
|
-
|
|
62
|
-
1. **Alphabetical grouping**: `persona_*` tools cluster together in tool lists
|
|
63
|
-
2. **Industry standard**: Matches Playwright, Firecrawl, Filesystem servers
|
|
64
|
-
3. **MCP spec compliant**: Allowed chars include underscore, examples show similar patterns
|
|
65
|
-
4. **Focused parameters**: Each tool only shows relevant options
|
|
66
|
-
5. **No mode confusion**: Operation is in the name
|
|
67
|
-
|
|
68
|
-
---
|
|
69
|
-
|
|
70
|
-
## Proposed Tool Set
|
|
71
|
-
|
|
72
|
-
### Core Tools (~32 total)
|
|
73
|
-
|
|
74
|
-
#### Persona Operations (8 tools)
|
|
75
|
-
|
|
76
|
-
| Tool | Description | Key Params |
|
|
77
|
-
|------|-------------|------------|
|
|
78
|
-
| `persona_list` | List AI Employees | `query?`, `status?`, `type?`, `limit?` |
|
|
79
|
-
| `persona_get` | Get specific persona | `id`, `include_workflow?` |
|
|
80
|
-
| `persona_create` | Create new persona | `name`, `type\|from`, `input?`, `preview?` |
|
|
81
|
-
| `persona_update` | Update config | `id`, `proto_config?`, `workflow?` |
|
|
82
|
-
| `persona_clone` | Clone persona | `from`, `name`, `include_data?`, `sanitize?` |
|
|
83
|
-
| `persona_analyze` | Analyze for issues | `id`, `fix?`, `include?` |
|
|
84
|
-
| `persona_sanitize` | Remove PII | `id`, `sanitize_examples?` |
|
|
85
|
-
| `persona_templates` | List templates | (none) |
|
|
86
|
-
|
|
87
|
-
#### Version Operations (4 tools)
|
|
88
|
-
|
|
89
|
-
| Tool | Description | Key Params |
|
|
90
|
-
|------|-------------|------------|
|
|
91
|
-
| `version_create` | Create snapshot | `persona_id`, `message?` |
|
|
92
|
-
| `version_list` | List versions | `persona_id` |
|
|
93
|
-
| `version_restore` | Restore version | `persona_id`, `version` |
|
|
94
|
-
| `version_policy` | Set version policy | `persona_id`, `auto_on_deploy?` |
|
|
95
|
-
|
|
96
|
-
#### Data Operations (7 tools)
|
|
97
|
-
|
|
98
|
-
| Tool | Description | Key Params |
|
|
99
|
-
|------|-------------|------------|
|
|
100
|
-
| `data_list` | List files | `persona_id`, `limit?` |
|
|
101
|
-
| `data_get` | Get specific file | `persona_id`, `file_id` |
|
|
102
|
-
| `data_upload` | Upload file | `persona_id`, `file`, `tags?` |
|
|
103
|
-
| `data_generate` | Generate content | `persona_id`, `from\|input`, `count?` |
|
|
104
|
-
| `data_delete` | Delete file | `persona_id`, `file_id` |
|
|
105
|
-
| `data_sanitize` | Sanitize data | `persona_id`, `include_workflow?` |
|
|
106
|
-
| `data_embedding` | Embedding status/toggle | `persona_id`, `enabled?` |
|
|
107
|
-
|
|
108
|
-
#### Action Operations (4 tools)
|
|
109
|
-
|
|
110
|
-
| Tool | Description | Key Params |
|
|
111
|
-
|------|-------------|------------|
|
|
112
|
-
| `action_list` | List workflow actions | `category?`, `limit?` |
|
|
113
|
-
| `action_get` | Get action details | `id`, `include_docs?` |
|
|
114
|
-
| `action_suggest` | Suggest for use case | `input` |
|
|
115
|
-
| `action_categories` | List categories | (none) |
|
|
116
|
-
|
|
117
|
-
#### Template Operations (4 tools)
|
|
118
|
-
|
|
119
|
-
| Tool | Description | Key Params |
|
|
120
|
-
|------|-------------|------------|
|
|
121
|
-
| `template_patterns` | List workflow patterns | `type?` |
|
|
122
|
-
| `template_pattern` | Get specific pattern | `name` |
|
|
123
|
-
| `template_widgets` | Get widget reference | `type` |
|
|
124
|
-
| `template_questions` | Get qualifying questions | `category?` |
|
|
125
|
-
|
|
126
|
-
#### Reference Operations (5 tools)
|
|
127
|
-
|
|
128
|
-
| Tool | Description | Key Params |
|
|
129
|
-
|------|-------------|------------|
|
|
130
|
-
| `reference_concept` | Get concept definition | `term` |
|
|
131
|
-
| `reference_concepts` | List all concepts | (none) |
|
|
132
|
-
| `reference_guidance` | Get topic guidance | `topic` |
|
|
133
|
-
| `reference_validate` | Validate types/prompt | `check_types?`, `validate_prompt?` |
|
|
134
|
-
| `reference_debug` | Get debug info | `type` (mistakes/checklist/execution) |
|
|
135
|
-
|
|
136
|
-
#### Sync Operations (3 tools)
|
|
137
|
-
|
|
138
|
-
| Tool | Description | Key Params |
|
|
139
|
-
|------|-------------|------------|
|
|
140
|
-
| `sync_run` | Sync to target env | `id?`, `target`, `scope?`, `dry_run?` |
|
|
141
|
-
| `sync_status` | Check sync status | `id?`, `list_synced?` |
|
|
142
|
-
| `sync_config` | Show sync config | (none) |
|
|
143
|
-
|
|
144
|
-
#### Environment (1 tool)
|
|
145
|
-
|
|
146
|
-
| Tool | Description | Key Params |
|
|
147
|
-
|------|-------------|------------|
|
|
148
|
-
| `env` | List environments | (none) |
|
|
149
|
-
|
|
150
|
-
---
|
|
151
|
-
|
|
152
|
-
## Prompts (User-Controlled Workflows)
|
|
153
|
-
|
|
154
|
-
Per MCP spec, prompts are for **user-initiated workflows**, not model-controlled operations.
|
|
155
|
-
|
|
156
|
-
### Proposed Prompts
|
|
157
|
-
|
|
158
|
-
| Prompt | Description | Arguments |
|
|
159
|
-
|--------|-------------|-----------|
|
|
160
|
-
| `create_voice_ai` | Guided Voice AI creation | `use_case`, `name?` |
|
|
161
|
-
| `create_chat_ai` | Guided Chat AI creation | `use_case`, `name?` |
|
|
162
|
-
| `clone_for_demo` | Clone + sanitize for demo | `source_id` |
|
|
163
|
-
| `troubleshoot` | Diagnose workflow issues | `persona_id` |
|
|
164
|
-
| `sync_to_production` | Safe production sync | `persona_id` |
|
|
165
|
-
| `migrate_persona` | Cross-env migration guide | `persona_id`, `target_env` |
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
## Migration Strategy
|
|
170
|
-
|
|
171
|
-
### Phase 1: Add New Tools (Non-Breaking)
|
|
172
|
-
|
|
173
|
-
1. Add all `{resource}_{action}` tools alongside existing tools
|
|
174
|
-
2. Both patterns work simultaneously
|
|
175
|
-
3. Document new pattern as preferred
|
|
176
|
-
|
|
177
|
-
### Phase 2: Deprecate Mode-Based Tools
|
|
178
|
-
|
|
179
|
-
1. Add deprecation warnings to mode-based tools
|
|
180
|
-
2. Route mode-based calls to new tools internally
|
|
181
|
-
3. Update documentation and examples
|
|
182
|
-
|
|
183
|
-
### Phase 3: Remove Deprecated Tools
|
|
184
|
-
|
|
185
|
-
1. Remove `workflow`, `knowledge`, `demo` (already deprecated)
|
|
186
|
-
2. Remove mode-based `persona`, `data`, `action`, etc.
|
|
187
|
-
3. Final tool count: ~32
|
|
188
|
-
|
|
189
|
-
### Backwards Compatibility
|
|
190
|
-
|
|
191
|
-
```typescript
|
|
192
|
-
// Internal routing for backwards compatibility
|
|
193
|
-
if (toolName === "persona" && args.mode) {
|
|
194
|
-
// Route to new tool
|
|
195
|
-
const newTool = `persona_${args.mode}`;
|
|
196
|
-
console.warn(`Deprecated: Use ${newTool} instead of persona(mode="${args.mode}")`);
|
|
197
|
-
return handleTool(newTool, args);
|
|
198
|
-
}
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
---
|
|
202
|
-
|
|
203
|
-
## Implementation Details
|
|
204
|
-
|
|
205
|
-
### Tool Definition Example
|
|
206
|
-
|
|
207
|
-
```typescript
|
|
208
|
-
// tools.ts
|
|
209
|
-
|
|
210
|
-
export const TOOLS: Tool[] = [
|
|
211
|
-
{
|
|
212
|
-
name: "persona_list",
|
|
213
|
-
description: "List AI Employees with optional filters",
|
|
214
|
-
inputSchema: {
|
|
215
|
-
type: "object",
|
|
216
|
-
properties: {
|
|
217
|
-
query: { type: "string", description: "Search by name" },
|
|
218
|
-
status: { type: "string", enum: ["active", "inactive", "draft"] },
|
|
219
|
-
type: { type: "string", enum: ["voice", "chat", "dashboard"] },
|
|
220
|
-
limit: { type: "number", description: "Max results (default: 50)" },
|
|
221
|
-
env: { type: "string", description: "Target environment" },
|
|
222
|
-
},
|
|
223
|
-
},
|
|
224
|
-
},
|
|
225
|
-
{
|
|
226
|
-
name: "persona_get",
|
|
227
|
-
description: "Get a specific AI Employee by ID",
|
|
228
|
-
inputSchema: {
|
|
229
|
-
type: "object",
|
|
230
|
-
properties: {
|
|
231
|
-
id: { type: "string", description: "Persona ID or name" },
|
|
232
|
-
include_workflow: { type: "boolean", description: "Include full workflow" },
|
|
233
|
-
env: { type: "string" },
|
|
234
|
-
},
|
|
235
|
-
required: ["id"],
|
|
236
|
-
},
|
|
237
|
-
},
|
|
238
|
-
// ... etc
|
|
239
|
-
];
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
### Handler Routing
|
|
243
|
-
|
|
244
|
-
```typescript
|
|
245
|
-
// server.ts
|
|
246
|
-
|
|
247
|
-
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
248
|
-
const { name, arguments: args } = request.params;
|
|
249
|
-
|
|
250
|
-
// Parse tool name: "persona_list" → resource="persona", action="list"
|
|
251
|
-
const [resource, action] = name.split("_");
|
|
252
|
-
|
|
253
|
-
switch (resource) {
|
|
254
|
-
case "persona":
|
|
255
|
-
return handlePersona(action, args);
|
|
256
|
-
case "data":
|
|
257
|
-
return handleData(action, args);
|
|
258
|
-
case "action":
|
|
259
|
-
return handleAction(action, args);
|
|
260
|
-
case "template":
|
|
261
|
-
return handleTemplate(action, args);
|
|
262
|
-
case "reference":
|
|
263
|
-
return handleReference(action, args);
|
|
264
|
-
case "sync":
|
|
265
|
-
return handleSync(action, args);
|
|
266
|
-
case "version":
|
|
267
|
-
return handleVersion(action, args);
|
|
268
|
-
case "env":
|
|
269
|
-
return handleEnv(args);
|
|
270
|
-
default:
|
|
271
|
-
throw new Error(`Unknown tool: ${name}`);
|
|
272
|
-
}
|
|
273
|
-
});
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
---
|
|
277
|
-
|
|
278
|
-
## Comparison Matrix
|
|
279
|
-
|
|
280
|
-
| Aspect | Current (mode-based) | Proposed (action-based) |
|
|
281
|
-
|--------|---------------------|------------------------|
|
|
282
|
-
| Tool count | 7 (+ 3 deprecated) | ~32 |
|
|
283
|
-
| Params per tool | 30+ | 3-8 |
|
|
284
|
-
| Discoverability | Poor (read long descriptions) | Excellent (scan tool names) |
|
|
285
|
-
| LLM clarity | Confusing modes | Clear operations |
|
|
286
|
-
| Industry alignment | Non-standard | Standard (Playwright, Firecrawl) |
|
|
287
|
-
| MCP spec alignment | Partial | Full |
|
|
288
|
-
| Alphabetical grouping | No | Yes (`persona_*` clusters) |
|
|
289
|
-
|
|
290
|
-
---
|
|
291
|
-
|
|
292
|
-
## Risks & Mitigations
|
|
293
|
-
|
|
294
|
-
| Risk | Mitigation |
|
|
295
|
-
|------|------------|
|
|
296
|
-
| Breaking existing integrations | Phased rollout with backwards compat routing |
|
|
297
|
-
| Tool count explosion | Capped at ~32, well-organized by prefix |
|
|
298
|
-
| Documentation churn | Generate docs from tool definitions |
|
|
299
|
-
| LLM token cost | More tools but simpler schemas (net neutral) |
|
|
300
|
-
|
|
301
|
-
---
|
|
302
|
-
|
|
303
|
-
## Success Metrics
|
|
304
|
-
|
|
305
|
-
1. **LLM accuracy**: Fewer incorrect tool calls
|
|
306
|
-
2. **Tool discovery**: Users find tools faster in lists
|
|
307
|
-
3. **Param errors**: Fewer "wrong param for this mode" issues
|
|
308
|
-
4. **Adoption**: New pattern used in 90%+ of calls within 30 days
|
|
309
|
-
|
|
310
|
-
---
|
|
311
|
-
|
|
312
|
-
## Files to Modify
|
|
313
|
-
|
|
314
|
-
| File | Changes |
|
|
315
|
-
|------|---------|
|
|
316
|
-
| `src/mcp/tools-consolidated.ts` | Replace with new tool definitions |
|
|
317
|
-
| `src/mcp/server.ts` | Update handler routing |
|
|
318
|
-
| `src/mcp/prompts.ts` | Add workflow prompts |
|
|
319
|
-
| `docs/mcp-tools-guide.md` | Document new pattern |
|
|
320
|
-
| `test/mcp-tools.test.ts` | Update tests |
|
|
321
|
-
|
|
322
|
-
---
|
|
323
|
-
|
|
324
|
-
## Timeline
|
|
325
|
-
|
|
326
|
-
| Phase | Scope |
|
|
327
|
-
|-------|-------|
|
|
328
|
-
| Phase 1 | Add new tools alongside existing |
|
|
329
|
-
| Phase 2 | Deprecate mode-based tools |
|
|
330
|
-
| Phase 3 | Remove deprecated tools |
|
|
331
|
-
|
|
332
|
-
---
|
|
333
|
-
|
|
334
|
-
## Appendix: Tool Name Mapping
|
|
335
|
-
|
|
336
|
-
| Current | New |
|
|
337
|
-
|---------|-----|
|
|
338
|
-
| `persona(mode="list")` | `persona_list` |
|
|
339
|
-
| `persona(mode="get", id="...")` | `persona_get` |
|
|
340
|
-
| `persona(mode="create", ...)` | `persona_create` |
|
|
341
|
-
| `persona(mode="update", ...)` | `persona_update` |
|
|
342
|
-
| `persona(mode="clone", ...)` | `persona_clone` |
|
|
343
|
-
| `persona(mode="analyze", ...)` | `persona_analyze` |
|
|
344
|
-
| `persona(mode="sanitize", ...)` | `persona_sanitize` |
|
|
345
|
-
| `persona(mode="templates")` | `persona_templates` |
|
|
346
|
-
| `data(mode="list", ...)` | `data_list` |
|
|
347
|
-
| `data(mode="upload", ...)` | `data_upload` |
|
|
348
|
-
| `data(mode="generate", ...)` | `data_generate` |
|
|
349
|
-
| `data(mode="delete", ...)` | `data_delete` |
|
|
350
|
-
| `action(all=true)` | `action_list` |
|
|
351
|
-
| `action(id="...")` | `action_get` |
|
|
352
|
-
| `action(suggest="...")` | `action_suggest` |
|
|
353
|
-
| `sync(mode="run", ...)` | `sync_run` |
|
|
354
|
-
| `sync(mode="status", ...)` | `sync_status` |
|
|
355
|
-
| `reference(concept="...")` | `reference_concept` |
|
|
356
|
-
| `reference(guidance="...")` | `reference_guidance` |
|
|
357
|
-
|
|
358
|
-
---
|
|
359
|
-
|
|
360
|
-
## References
|
|
361
|
-
|
|
362
|
-
- [MCP Specification - Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
|
|
363
|
-
- [MCP Specification - Prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts)
|
|
364
|
-
- [Playwright MCP Server](https://github.com/microsoft/playwright-mcp)
|
|
365
|
-
- [Firecrawl MCP Server](https://github.com/firecrawl/firecrawl-mcp-server)
|
|
366
|
-
- [Awesome MCP Servers](https://mcpservers.org/)
|