@walkeros/mcp 2.0.1 → 3.0.0

package/README.md

@@ -1,221 +0,0 @@
-# @walkeros/mcp
-
-MCP server for walkerOS — validate, bundle, and simulate analytics events
-locally, plus manage projects and flows via the walkerOS API.
-
-## Installation
-
-```bash
-npm install @walkeros/mcp
-```
-
-## Environment Variables
-
-| Variable              | Required                   | Default                   | Purpose                          |
-| --------------------- | -------------------------- | ------------------------- | -------------------------------- |
-| `WALKEROS_TOKEN`      | Yes (API tools)            | —                         | Bearer token (`sk-walkeros-...`) |
-| `WALKEROS_PROJECT_ID` | Yes (project-scoped tools) | —                         | Active project ID (`proj_...`)   |
-| `WALKEROS_APP_URL`    | No                         | `https://app.walkeros.io` | Base URL override                |
-
-API tools require `WALKEROS_TOKEN`. Project-scoped tools (flows) also need
-`WALKEROS_PROJECT_ID`, or you can pass `projectId` as a parameter.
-
-## Usage with Claude Desktop
-
-```json
-{
-  "mcpServers": {
-    "walkeros": {
-      "command": "npx",
-      "args": ["@walkeros/mcp"],
-      "env": {
-        "WALKEROS_TOKEN": "sk-walkeros-...",
-        "WALKEROS_PROJECT_ID": "proj_..."
-      }
-    }
-  }
-}
-```
-
-## Usage with Claude Code
-
-```json
-{
-  "mcpServers": {
-    "walkeros": {
-      "command": "npx",
-      "args": ["@walkeros/mcp"],
-      "env": {
-        "WALKEROS_TOKEN": "sk-walkeros-...",
-        "WALKEROS_PROJECT_ID": "proj_..."
-      }
-    }
-  }
-}
-```
-
-## Available Tools (17)
-
-### Local CLI Tools
-
-#### `validate`
-
-Validate walkerOS events, flow configurations, or mapping rules.
-
-- `type` (required): `"event"` | `"flow"` | `"mapping"`
-- `input` (required): JSON string or file path to validate
-- `flow` (optional): Flow name to validate against
-
-#### `bundle`
-
-Bundle a walkerOS flow configuration into deployable JavaScript. Supports both
-local bundling (via CLI) and remote cloud bundling (via API).
-
-- `configPath` (optional): Path to the flow configuration file (local mode)
-- `flow` (optional): Specific flow name to bundle
-- `stats` (optional): Include bundle statistics in output
-- `output` (optional): Output file path for the bundle
-- `remote` (optional): Use remote cloud bundling (requires `WALKEROS_TOKEN`)
-- `content` (optional): Flow.Setup JSON content (required when `remote: true`)
-
-#### `simulate`
-
-Simulate events through a walkerOS flow without making real API calls.
-
-- `configPath` (required): Path to the flow configuration file
-- `event` (required): JSON string representing the event to simulate
-- `flow` (optional): Flow name to simulate through
-- `platform` (optional): `"web"` | `"server"` (default: `"web"`)
-
-#### `push`
-
-Push a real event through a walkerOS flow to actual destinations. WARNING: This
-makes real API calls to real endpoints.
-
-- `configPath` (required): Path to the flow configuration file
-- `event` (required): JSON string representing the event to push
-- `flow` (optional): Flow name for multi-flow configs
-- `platform` (optional): `"web"` | `"server"` (default: `"web"`)
-
-### Auth
-
-#### `whoami`
-
-Verify your API token and see your identity. Returns user ID, email, and project
-ID.
-
-### Projects
-
-#### `list-projects`
-
-List all projects you have access to.
-
-#### `get-project`
-
-Get details for a project. Uses `WALKEROS_PROJECT_ID` if `projectId` is omitted.
-
-- `projectId` (optional): Project ID
-
-#### `create-project`
-
-Create a new project.
-
-- `name` (required): Project name
-
-#### `update-project`
-
-Update a project name.
-
-- `projectId` (optional): Project ID
-- `name` (required): New project name
-
-#### `delete-project`
-
-Soft-delete a project and all its flows.
-
-- `projectId` (optional): Project ID
-
-### Flows
-
-#### `list-flows`
-
-List all flow configurations in a project.
-
-- `projectId` (optional): Project ID
-- `sort` (optional): `"name"` | `"updated_at"` | `"created_at"`
-- `order` (optional): `"asc"` | `"desc"`
-- `includeDeleted` (optional): Include soft-deleted flows
-
-#### `get-flow`
-
-Get a flow configuration with its full content.
-
-- `flowId` (required): Flow ID (`cfg_...`)
-- `projectId` (optional): Project ID
-
-#### `create-flow`
-
-Create a new flow configuration.
-
-- `name` (required): Flow name
-- `content` (required): Flow.Setup JSON content
-- `projectId` (optional): Project ID
-
-#### `update-flow`
-
-Update a flow name and/or content.
-
-- `flowId` (required): Flow ID (`cfg_...`)
-- `name` (optional): New flow name
-- `content` (optional): New Flow.Setup JSON content
-- `projectId` (optional): Project ID
-
-#### `delete-flow`
-
-Soft-delete a flow configuration.
-
-- `flowId` (required): Flow ID (`cfg_...`)
-- `projectId` (optional): Project ID
-
-#### `duplicate-flow`
-
-Create a copy of an existing flow configuration.
-
-- `flowId` (required): Flow ID to duplicate (`cfg_...`)
-- `name` (optional): Name for the copy
-- `projectId` (optional): Project ID
-
-## Local Development
-
-### Smoke Test
-
-A script exercises all API endpoints against a running app instance:
-
-```bash
-WALKEROS_TOKEN='<your-token>' \
-WALKEROS_APP_URL=http://localhost:3000 \
-WALKEROS_PROJECT_ID='<your-project-id>' \
-npx tsx packages/mcp/scripts/smoke-test.ts
-```
-
-### Updating the OpenAPI Baseline
-
-The contract test (`npm test`) checks that all MCP endpoints exist in a snapshot
-of the app's OpenAPI spec. After API changes:
-
-```bash
-curl $WALKEROS_APP_URL/api/openapi.json | python3 -m json.tool \
-  > packages/mcp/src/__tests__/fixtures/openapi-baseline.json
-```
-
-## Dependencies
-
-This package depends on:
-
-- `@walkeros/cli` — walkerOS command-line interface (validate, bundle, simulate,
-  push)
-- `@modelcontextprotocol/sdk` — Model Context Protocol server framework
-
-## License
-
-MIT