@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.

Files changed (87) hide show
  1. package/README.md +10 -2
  2. package/dist/mcp/handlers/action/index.js +3 -18
  3. package/dist/mcp/handlers/data/index.js +385 -41
  4. package/dist/mcp/handlers/data/templates.js +107 -0
  5. package/dist/mcp/handlers/deprecation.js +50 -0
  6. package/dist/mcp/handlers/env/index.js +8 -4
  7. package/dist/mcp/handlers/knowledge/index.js +44 -237
  8. package/dist/mcp/handlers/persona/create.js +47 -18
  9. package/dist/mcp/handlers/persona/index.js +14 -11
  10. package/dist/mcp/handlers/persona/update.js +4 -2
  11. package/dist/mcp/handlers/persona/version.js +234 -0
  12. package/dist/mcp/handlers/sync/index.js +3 -18
  13. package/dist/mcp/handlers/template/index.js +75 -10
  14. package/dist/mcp/handlers/workflow/analyze.js +171 -0
  15. package/dist/mcp/handlers/workflow/compare.js +70 -0
  16. package/dist/mcp/handlers/workflow/deploy.js +73 -0
  17. package/dist/mcp/handlers/workflow/generate.js +350 -0
  18. package/dist/mcp/handlers/workflow/index.js +294 -0
  19. package/dist/mcp/handlers/workflow/modify.js +456 -0
  20. package/dist/mcp/handlers/workflow/optimize.js +136 -0
  21. package/dist/mcp/handlers/workflow/types.js +4 -0
  22. package/dist/mcp/handlers/workflow/utils.js +30 -0
  23. package/dist/mcp/handlers-consolidated.js +73 -2696
  24. package/dist/mcp/prompts.js +83 -43
  25. package/dist/mcp/resources.js +382 -57
  26. package/dist/mcp/server.js +199 -391
  27. package/dist/mcp/{tools-v2.js → tools.js} +20 -54
  28. package/dist/mcp/workflow-operations.js +2 -2
  29. package/dist/sdk/client-adapter.js +267 -32
  30. package/dist/sdk/client.js +45 -16
  31. package/dist/sdk/ema-client.js +183 -0
  32. package/dist/sdk/generated/deprecated-actions.js +171 -0
  33. package/dist/sdk/generated/template-fallbacks.js +123 -0
  34. package/dist/sdk/guidance.js +65 -11
  35. package/dist/sdk/index.js +3 -1
  36. package/dist/sdk/knowledge.js +139 -86
  37. package/dist/sdk/workflow-intent.js +27 -0
  38. package/dist/sdk/workflow-transformer.js +0 -342
  39. package/docs/mcp-tools-guide.md +37 -45
  40. package/package.json +10 -4
  41. package/dist/mcp/handlers/persona/analyze.js +0 -275
  42. package/dist/mcp/handlers/persona/compare.js +0 -32
  43. package/dist/mcp/tools-consolidated.js +0 -875
  44. package/dist/mcp/tools-legacy.js +0 -736
  45. package/docs/CODEBASE-ANALYSIS-2026-01-23.md +0 -936
  46. package/docs/CODEBASE-ANALYSIS-PRIORITIZED.md +0 -774
  47. package/docs/api-contracts.md +0 -216
  48. package/docs/auto-builder-analysis.md +0 -271
  49. package/docs/blog/mcp-tool-design-lessons.md +0 -309
  50. package/docs/data-architecture.md +0 -166
  51. package/docs/demos/ap-invoice-generation.md +0 -347
  52. package/docs/demos/ap-invoice-processing.md +0 -271
  53. package/docs/ema-auto-builder-guide.html +0 -394
  54. package/docs/lessons-learned.md +0 -209
  55. package/docs/llm-native-workflow-design.md +0 -252
  56. package/docs/local-generation.md +0 -508
  57. package/docs/mcp-flow-diagram.md +0 -135
  58. package/docs/migration/action-composition-migration.md +0 -270
  59. package/docs/naming-conventions.md +0 -278
  60. package/docs/proposals/HANDOFF-tool-restructure.md +0 -526
  61. package/docs/proposals/action-composition.md +0 -490
  62. package/docs/proposals/explicit-method-restructure.md +0 -328
  63. package/docs/proposals/mcp-tool-restructure-2026-01.md +0 -366
  64. package/docs/proposals/self-contained-guidance.md +0 -427
  65. package/docs/proto-sdk-generation.md +0 -242
  66. package/docs/release-impact.md +0 -102
  67. package/docs/release-process.md +0 -157
  68. package/docs/staging.RULE.md +0 -142
  69. package/docs/test-persona-creation.md +0 -196
  70. package/docs/tool-consolidation-v2.md +0 -225
  71. package/docs/tool-response-standards.md +0 -256
  72. package/resources/demo-kits/README.md +0 -175
  73. package/resources/demo-kits/finance-ap/manifest.json +0 -150
  74. package/resources/demo-kits/tags.json +0 -91
  75. package/resources/docs/getting-started.md +0 -97
  76. package/resources/templates/auto-builder-rules.md +0 -224
  77. package/resources/templates/chat-ai/README.md +0 -119
  78. package/resources/templates/chat-ai/persona-config.json +0 -111
  79. package/resources/templates/dashboard-ai/README.md +0 -156
  80. package/resources/templates/dashboard-ai/persona-config.json +0 -180
  81. package/resources/templates/demo-scenarios/README.md +0 -63
  82. package/resources/templates/demo-scenarios/test-published-package.md +0 -116
  83. package/resources/templates/document-gen-ai/README.md +0 -132
  84. package/resources/templates/document-gen-ai/persona-config.json +0 -316
  85. package/resources/templates/voice-ai/README.md +0 -123
  86. package/resources/templates/voice-ai/persona-config.json +0 -74
  87. 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/)