@walkeros/mcp 4.8.0 → 4.8.1-next-1792019907609

package/README.md

@@ -6,9 +6,9 @@
 
 # @walkeros/mcp
 
-Model Context Protocol server for walkerOS flow development. Gives an AI
-assistant the tools to discover packages, build a flow configuration, validate
-it, simulate events through it, bundle it, and deploy it.
+The local walkerOS MCP server: validate, simulate, bundle and push flows on your
+own machine; the hosted server at https://app.walkeros.io/api/mcp covers what
+the walkerOS app stores.
 
 [Documentation](https://www.walkeros.io/docs/apps/mcp) •
 [NPM Package](https://www.npmjs.com/package/@walkeros/mcp) •
@@ -16,6 +16,12 @@ it, simulate events through it, bundle it, and deploy it.
 
 ## Installation
 
+```bash
+npm install @walkeros/mcp
+```
+
+## Quick start
+
 The server runs over stdio and is started by your MCP client. Add it to the
 client's configuration:
 
@@ -30,184 +36,10 @@ client's configuration:
 }
 ```
 
-| Client         | File                                                       |
-| -------------- | ---------------------------------------------------------- |
-| Claude Code    | `.mcp.json` in the project root                            |
-| Cursor         | `.cursor/mcp.json` in the project root                     |
-| Claude Desktop | `claude_desktop_config.json`                               |
-| VS Code        | `.vscode/mcp.json`, with `servers` instead of `mcpServers` |
-
-In Claude Code you can also install the walkerOS plugin, which registers this
-server, the tagging server, and the walkerOS skills in one step:
-
-```
-/plugin marketplace add elbwalker/walkerOS
-/plugin install walkeros@elbwalker
-```
-
-To install the binary directly instead of running it through `npx`:
-
-```bash
-npm install @walkeros/mcp
-```
-
-## No account required
-
-The server starts, registers all tools, and runs the whole local loop without
-any credentials. `auth` reports `{ "authenticated": false }` and the local tools
-work regardless. Only the walkerOS cloud tools need a credential.
-
-Two ways to get one:
-
-- **`auth` with `action: "login"`** runs the RFC 8628 device authorization
-  grant. It answers with a URL, you approve it in a browser you are already
-  signed in to, and a second call with the same `deviceCode` resumes polling
-  until the approval lands. The session that results refreshes itself, and it
-  appears in the app under Account, Connected apps, where disconnecting it takes
-  effect on the next call. `auth` with `action: "logout"` revokes it.
-- **`WALKEROS_TOKEN`** carries an automation token (`wos_pat_...`) minted in the
-  app under Account, then Automation tokens. It is used as-is and never
-  refreshed, which is what a CI job or a headless server wants.
-
-There is no endpoint that mints a token from another token, and nothing issues
-`sk-walkeros-` or `mcp-walkeros-` values any more; rows carrying them keep
-verifying until they expire.
-
-## Quick start
-
-Five tools cover building a flow from nothing to a tested configuration, and all
-five run locally:
-
-1. **`flow_load`** creates an empty flow for a platform, or loads an existing
-   one from a file, URL, or inline JSON.
-2. **`package_search`** finds the exact package names for the sources,
-   destinations, transformers, and stores the flow needs. Never guess a package
-   name, search for it.
-3. **`package_get`** returns that package's configuration schema, hints, and
-   worked examples, so the config is written against the real shape.
-4. **`flow_validate`** checks the result. Fix and re-validate until it passes.
-5. **`flow_simulate`** pushes an event through the flow with vendor calls mocked
-   and shows what each step produced.
-
-## Tools
-
-The server registers 19 tools.
-
-### Local, no account
-
-| Tool             | Description                                                                          |
-| ---------------- | ------------------------------------------------------------------------------------ |
-| `flow_load`      | Load a flow from a file path, URL, inline JSON, or flow ID, or create an empty one   |
-| `flow_validate`  | Validate an event, flow config, mapping rule, or data contract                       |
-| `flow_simulate`  | Run an event through a flow with mocked vendor calls and inspect each step           |
-| `flow_bundle`    | Compile a flow into a tree-shaken, deployable JavaScript bundle                      |
-| `flow_push`      | Push a real event through a flow to real destinations, making real API calls         |
-| `flow_examples`  | List the step examples in a flow, the fixtures simulation can replay                 |
-| `package_search` | Find packages by name, type, or platform. The entry point for package discovery      |
-| `package_get`    | Read one package's schemas, configuration hints, and examples by exact name          |
-| `diagnostics`    | Report MCP and CLI versions, app URL, app reachability, and the API contract verdict |
-
-### walkerOS cloud
-
-| Tool               | Description                                                                               |
-| ------------------ | ----------------------------------------------------------------------------------------- |
-| `auth`             | Check login status, log in through the device code flow, or log out                       |
-| `project_manage`   | List, create, update, or delete projects, and set the default one                         |
-| `flow_manage`      | List, create, update, delete, or duplicate saved flows, and manage their previews         |
-| `deploy_manage`    | Deploy a flow and list, inspect, or delete its deployments                                |
-| `secret_manage`    | Manage a flow's `$secret.<NAME>` values. Write-mostly, values are never returned          |
-| `observe_session`  | Start, inspect, or stop an Observe session, a time-boxed window on one running flow       |
-| `observe_journeys` | Read the assembled journeys for an observed flow, each event traced across web and server |
-| `hub_manage`       | Read a flow's release history and the reasoning behind it, and add to the discussion      |
-| `frame_manage`     | Read the frames of a measurement plan, the named rectangles and the marks inside them     |
-| `feedback`         | Send feedback about walkerOS                                                              |
-
-## Resources
-
-| URI                                | Content                                                         |
-| ---------------------------------- | --------------------------------------------------------------- |
-| `walkeros://reference/flow-schema` | Flow configuration structure and connection rules               |
-| `walkeros://reference/event-model` | Event naming, properties, and auto-populated fields             |
-| `walkeros://reference/mapping`     | Mapping syntax: data, map, loop, set, condition, policy         |
-| `walkeros://reference/consent`     | The consent model at destination and field level                |
-| `walkeros://reference/variables`   | Variable patterns: `$var`, `$env`, `$secret`, `$code`, `$store` |
-| `walkeros://reference/contract`    | Event schemas, wildcards, and inheritance                       |
-| `walkeros://reference/openapi`     | The live OpenAPI 3.1 document of the app this server talks to   |
-| `walkeros://reference/packages`    | The full package catalog                                        |
-| `walkeros://schema/{packageName}`  | JSON schema for one package                                     |
-
-Read these before writing a configuration by hand.
-
-## Prompts
-
-| Prompt            | Purpose                                                            |
-| ----------------- | ------------------------------------------------------------------ |
-| `add-step`        | Add a source, destination, transformer, or store to a flow         |
-| `setup-mapping`   | Configure event mapping for a step                                 |
-| `manage-contract` | Create or update event contracts, in both directions with mappings |
-
-## Environment variables
-
-| Variable              | Required | Default                   | Purpose                                                                    |
-| --------------------- | -------- | ------------------------- | -------------------------------------------------------------------------- |
-| `WALKEROS_TOKEN`      | No       | none                      | Automation token (`wos_pat_...`), an alternative to the `auth` tool login  |
-| `WALKEROS_PROJECT_ID` | No       | none                      | Project (`proj_...`) for calls without `projectId`, ahead of `set_default` |
-| `WALKEROS_APP_URL`    | No       | `https://app.walkeros.io` | Base URL override                                                          |
-
-## Programmatic usage
-
-The package exports a transport-agnostic server factory, so a host application
-can mount the protocol over HTTP instead of running the stdio binary:
-
-```typescript
-import {
-  createWalkerOSMcpServer,
-  createHostedRuntime,
-  HttpToolClient,
-  createStreamableHttpHandler,
-} from '@walkeros/mcp';
-
-const client = new HttpToolClient();
-const server = createWalkerOSMcpServer({
-  client,
-  version: '1.0.0',
-  runtime: createHostedRuntime(client),
-});
-
-export const POST = createStreamableHttpHandler(server, {
-  sessionIdGenerator: () => crypto.randomUUID(),
-});
-```
-
-The server reads, bundles and runs flows only through a runtime, which decides
-what the process it lives in may do. `createHostedRuntime(client)` is the
-default when `runtime` is omitted and the right choice for anything reached over
-the network: it loads inline JSON and saved flow ids, refuses local file paths
-and URLs, and never bundles, simulates or pushes in the host process.
-`createLocalRuntime()` keeps every capability, including local files, URLs and
-in-process execution, and belongs only on the user's own machine; the stdio
-binary uses it.
-
-To use the tool registry without the MCP protocol, for example with the Vercel
-AI SDK, call `createToolHandlers(client, version, runtime)` or import
-`TOOL_DEFINITIONS` and supply your own `ToolClient`. The stdio binary stays
-available as `@walkeros/mcp/stdio` and the `walkeros-mcp` bin entry.
-
-A `ToolClient` served inside a host that authenticates every request itself
-returns `'host'` from `credentialSource()`. The `auth` tool then reports the
-connection as logged in, answers `login` with "no login needed" and refuses
-`logout`, which never reaches the client: the connection ends in the host.
-
-A `ToolClient` may implement `checkContract()` and `openapiDocument()`. The
-`diagnostics` tool reports the first as its contract verdict, `unknown` when it
-is absent; the `walkeros://reference/openapi` resource serves the second.
-`HttpToolClient` implements both against the app it talks to. The tool roster
-ships as `@walkeros/mcp/surface.json`.
-
 ## Documentation
 
-Full parameter tables, workflows, and examples live in the docs:
-**https://www.walkeros.io/docs/apps/mcp**
+Tools, resources, prompts, programmatic usage and the hosted server live in the
+docs: **https://www.walkeros.io/docs/apps/mcp**
 
 ## Contribute