@walkeros/mcp 4.4.0 → 4.5.0

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.
Files changed (6) hide show
  1. package/README.md +181 -0
  2. package/dist/index.js +6356 -4982
  3. package/dist/index.js.map +1 -1
  4. package/dist/stdio.js +6359 -4985
  5. package/dist/stdio.js.map +1 -1
  6. package/package.json +12 -4
package/README.md ADDED
@@ -0,0 +1,181 @@
1
+ <p align="left">
2
+ <a href="https://www.walkeros.io">
3
+ <img alt="walkerOS" title="walkerOS" src="https://www.walkeros.io/img/walkerOS_logo.svg" width="256px"/>
4
+ </a>
5
+ </p>
6
+
7
+ # @walkeros/mcp
8
+
9
+ Model Context Protocol server for walkerOS flow development. Gives an AI
10
+ assistant the tools to discover packages, build a flow configuration, validate
11
+ it, simulate events through it, bundle it, and deploy it.
12
+
13
+ [Documentation](https://www.walkeros.io/docs/apps/mcp) &bull;
14
+ [NPM Package](https://www.npmjs.com/package/@walkeros/mcp) &bull;
15
+ [Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/mcps/mcp)
16
+
17
+ ## Installation
18
+
19
+ The server runs over stdio and is started by your MCP client. Add it to the
20
+ client's configuration:
21
+
22
+ ```json
23
+ {
24
+ "mcpServers": {
25
+ "walkeros-flow": {
26
+ "command": "npx",
27
+ "args": ["@walkeros/mcp"]
28
+ }
29
+ }
30
+ }
31
+ ```
32
+
33
+ | Client | File |
34
+ | -------------- | ---------------------------------------------------------- |
35
+ | Claude Code | `.mcp.json` in the project root |
36
+ | Cursor | `.cursor/mcp.json` in the project root |
37
+ | Claude Desktop | `claude_desktop_config.json` |
38
+ | VS Code | `.vscode/mcp.json`, with `servers` instead of `mcpServers` |
39
+
40
+ In Claude Code you can also install the walkerOS plugin, which registers this
41
+ server, the tagging server, and the walkerOS skills in one step:
42
+
43
+ ```
44
+ /plugin marketplace add elbwalker/walkerOS
45
+ /plugin install walkeros@elbwalker
46
+ ```
47
+
48
+ To install the binary directly instead of running it through `npx`:
49
+
50
+ ```bash
51
+ npm install @walkeros/mcp
52
+ ```
53
+
54
+ ## No account required
55
+
56
+ The server starts, registers all tools, and runs the whole local loop without
57
+ any credentials. `auth` reports `{ "authenticated": false }` and the local tools
58
+ work regardless. Only the walkerOS cloud tools need a login, either through the
59
+ `auth` tool's device code flow or a `WALKEROS_TOKEN` environment variable.
60
+
61
+ ## Quick start
62
+
63
+ Five tools cover building a flow from nothing to a tested configuration, and all
64
+ five run locally:
65
+
66
+ 1. **`flow_load`** creates an empty flow for a platform, or loads an existing
67
+ one from a file, URL, or inline JSON.
68
+ 2. **`package_search`** finds the exact package names for the sources,
69
+ destinations, transformers, and stores the flow needs. Never guess a package
70
+ name, search for it.
71
+ 3. **`package_get`** returns that package's configuration schema, hints, and
72
+ worked examples, so the config is written against the real shape.
73
+ 4. **`flow_validate`** checks the result. Fix and re-validate until it passes.
74
+ 5. **`flow_simulate`** pushes an event through the flow with vendor calls mocked
75
+ and shows what each step produced.
76
+
77
+ ## Tools
78
+
79
+ The server registers 17 tools.
80
+
81
+ ### Local, no account
82
+
83
+ | Tool | Description |
84
+ | ---------------- | ---------------------------------------------------------------------------------- |
85
+ | `flow_load` | Load a flow from a file path, URL, inline JSON, or flow ID, or create an empty one |
86
+ | `flow_validate` | Validate an event, flow config, mapping rule, or data contract |
87
+ | `flow_simulate` | Run an event through a flow with mocked vendor calls and inspect each step |
88
+ | `flow_bundle` | Compile a flow into a tree-shaken, deployable JavaScript bundle |
89
+ | `flow_push` | Push a real event through a flow to real destinations, making real API calls |
90
+ | `flow_examples` | List the step examples in a flow, the fixtures simulation can replay |
91
+ | `package_search` | Find packages by name, type, or platform. The entry point for package discovery |
92
+ | `package_get` | Read one package's schemas, configuration hints, and examples by exact name |
93
+ | `diagnostics` | Report MCP and CLI versions, app URL, backend, and whether the app is reachable |
94
+
95
+ ### walkerOS cloud
96
+
97
+ | Tool | Description |
98
+ | ------------------ | ----------------------------------------------------------------------------------------- |
99
+ | `auth` | Check login status, log in through the device code flow, or log out |
100
+ | `project_manage` | List, create, update, or delete projects, and set the default one |
101
+ | `flow_manage` | List, create, update, delete, or duplicate saved flows, and manage their previews |
102
+ | `deploy_manage` | Deploy a flow and list, inspect, or delete its deployments |
103
+ | `secret_manage` | Manage a flow's `$secret.<NAME>` values. Write-mostly, values are never returned |
104
+ | `observe_session` | Start, inspect, or stop an Observe session, a time-boxed window on one running flow |
105
+ | `observe_journeys` | Read the assembled journeys for an observed flow, each event traced across web and server |
106
+ | `feedback` | Send feedback about walkerOS |
107
+
108
+ ## Resources
109
+
110
+ | URI | Content |
111
+ | ---------------------------------- | --------------------------------------------------------------- |
112
+ | `walkeros://reference/flow-schema` | Flow configuration structure and connection rules |
113
+ | `walkeros://reference/event-model` | Event naming, properties, and auto-populated fields |
114
+ | `walkeros://reference/mapping` | Mapping syntax: data, map, loop, set, condition, policy |
115
+ | `walkeros://reference/consent` | The consent model at destination, rule, and field level |
116
+ | `walkeros://reference/variables` | Variable patterns: `$var`, `$env`, `$secret`, `$code`, `$store` |
117
+ | `walkeros://reference/contract` | Event schemas, wildcards, and inheritance |
118
+ | `walkeros://reference/openapi` | OpenAPI 3.1 specification for the walkerOS API |
119
+ | `walkeros://reference/packages` | The full package catalog |
120
+ | `walkeros://schema/{packageName}` | JSON schema for one package |
121
+
122
+ Read these before writing a configuration by hand.
123
+
124
+ ## Prompts
125
+
126
+ | Prompt | Purpose |
127
+ | ----------------- | ------------------------------------------------------------------ |
128
+ | `add-step` | Add a source, destination, transformer, or store to a flow |
129
+ | `setup-mapping` | Configure event mapping for a step |
130
+ | `manage-contract` | Create or update event contracts, in both directions with mappings |
131
+
132
+ ## Environment variables
133
+
134
+ | Variable | Required | Default | Purpose |
135
+ | --------------------- | -------- | ------------------------- | ----------------------------------------------------- |
136
+ | `WALKEROS_TOKEN` | No | none | Bearer token, an alternative to the `auth` tool login |
137
+ | `WALKEROS_PROJECT_ID` | No | none | Active project ID (`proj_...`) |
138
+ | `WALKEROS_APP_URL` | No | `https://app.walkeros.io` | Base URL override |
139
+
140
+ ## Programmatic usage
141
+
142
+ The package exports a transport-agnostic server factory, so a host application
143
+ can mount the protocol over HTTP instead of running the stdio binary:
144
+
145
+ ```typescript
146
+ import {
147
+ createWalkerOSMcpServer,
148
+ HttpToolClient,
149
+ createStreamableHttpHandler,
150
+ } from '@walkeros/mcp';
151
+
152
+ const server = createWalkerOSMcpServer({
153
+ client: new HttpToolClient(),
154
+ version: '1.0.0',
155
+ });
156
+
157
+ export const POST = createStreamableHttpHandler(server, {
158
+ sessionIdGenerator: () => crypto.randomUUID(),
159
+ });
160
+ ```
161
+
162
+ To use the tool registry without the MCP protocol, for example with the Vercel
163
+ AI SDK, import `TOOL_DEFINITIONS` and supply your own `ToolClient`. The stdio
164
+ binary stays available as `@walkeros/mcp/stdio` and the `walkeros-mcp` bin
165
+ entry.
166
+
167
+ ## Documentation
168
+
169
+ Full parameter tables, workflows, and examples live in the docs:
170
+ **https://www.walkeros.io/docs/apps/mcp**
171
+
172
+ ## Contribute
173
+
174
+ Feel free to contribute by submitting an
175
+ [issue](https://github.com/elbwalker/walkerOS/issues), starting a
176
+ [discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
177
+ [contact](https://calendly.com/elb-alexander/30min).
178
+
179
+ ## License
180
+
181
+ MIT