flowstate-epic-flowstate-community-epicdm-flowstate-mcp-gateway
Package-local agent skill for @epicdm/flowstate-mcp-gateway.
Tags
Publisher
Versions
1 version published — latest: 1.1.6
- 1.1.6publishedInvalid Date
Skill
flowstate-mcp-gateway Package Skill
Package: @epicdm/flowstate-mcp-gateway
Repository: epic-flowstate-community
Path: packages/flowstate-mcp-gateway
Version: 1.1.6
Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.
Primary Package Workflow
MCP Gateway Auth Isolation
Use this skill when a task touches request auth, token forwarding, concurrency, or privilege boundaries.
Current Model
extractRequestToken()accepts bearer tokens that look like JWTs orepic_tokens.withTokenLock()serializes token mutation and tool request execution.- If a valid token exists, the gateway mutates private
mcpServer.config.authToken. - The tool call is sent through
InMemoryTransport.
Known Risk
The lock prevents concurrent token swaps from racing. It does not restore the previous/default token after a request. A later request with no valid Authorization header can inherit the last accepted token.
Also, CLI config requires RXDB_AUTH_TOKEN, but the constructor does not pass it into FlowStateMCPServer; the documented fallback behavior is not reliable until fixed.
Required Tests Before Claiming Safe Auth
- Valid token A and valid token B concurrent requests remain isolated.
- Valid token followed by no Authorization does not inherit token A.
- Valid token followed by malformed Authorization does not inherit token A.
- Initial configured token is actually used when no request token is present, or docs stop claiming fallback.
Do Not
- Do not remove serialization without replacing it with request-scoped auth in the embedded MCP server.
- Do not log bearer tokens.
- Do not publish generated Dojo content that describes auth as solved without these caveats.
Package Skill Inventory
Package Skill Inventory: @epicdm/flowstate-mcp-gateway
Skill Map
| Skill | Type | Trigger | Teaches | Dojo |
|---|---|---|---|---|
flowstate-mcp-gateway | orchestrator | Use when integrating, modifying, or operating the local MCP HTTP gateway | Package purpose, local-only boundary, skill routing | local-only |
flowstate-mcp-gateway-http-api | workflow/reference | Use when calling or testing /health, /mcp/tools, or /mcp/tools/call | Route contracts, request/response shapes, lifecycle states | ready-after-review |
flowstate-mcp-gateway-auth-isolation | workflow/troubleshooting | Use when changing bearer-token forwarding, auth fallback, or concurrent request behavior | Token extraction, serialized mutation, missing restore risk, required tests | ready-after-review |
flowstate-mcp-gateway-cli-runtime | workflow | Use when running the standalone CLI with env vars, CORS, RxDB, and shutdown behavior | Env validation, startup logs, CORS, graceful shutdown | ready-after-review |
flowstate-mcp-gateway-transport-contract | reference/maintenance | Use when touching InMemoryTransport or private FlowStateMCPServer bridge behavior | MCP SDK bridge, private server access, timeout behavior | ready-after-review |
flowstate-mcp-gateway-verification | maintenance | Use when validating tests, lint warnings, integration script, docs, or Dojo sync | Verification commands, known warnings, docs drift, Dojo gate | local-only |
Anti-Sprawl Decision
Do not create one skill per route. The gateway is small; route behavior, auth isolation, CLI runtime, and transport contract are the real teaching boundaries.
Deferred Skills
- Cloud MCP gateway skill: defer to
worker-mcpor platform repos. - Dedicated CORS skill: fold into CLI/runtime unless CORS grows more complex.
- Dedicated
flowstate-mcp-clientskill: owned by the client package.
Review Gate
Package Skills Review: @epicdm/flowstate-mcp-gateway
Verdict
Pass with fixes.
The skillset focuses on local HTTP gateway operation and auth isolation instead of generated route snippets.
Findings
| Severity | Skill | Issue | Evidence | Required Fix |
|---|---|---|---|---|
| High | auth-isolation | Missing valid auth on a later request can inherit the last accepted token because the lock does not restore prior/default token state | src/server.ts | Fix or explicitly track before Dojo publication |
| High | cli-runtime/auth | CLI requires RXDB_AUTH_TOKEN, but server constructor does not pass it to FlowStateMCPServer | src/cli.ts, src/server.ts | Fix docs or implementation |
| Important | transport-contract | Gateway depends on private MCP server internals | src/server.ts | Track as fragile contract |
| Important | verification | Lint passes with many warnings; route auth coverage is too thin | review worker | Add targeted tests before publish |
Verification
Review worker ran:
yarn workspace @epicdm/flowstate-mcp-gateway test --runInBand
yarn workspace @epicdm/flowstate-mcp-gateway typecheck
yarn workspace @epicdm/flowstate-mcp-gateway lint
Results:
-
Tests passed.
-
Typecheck passed.
-
Lint exited 0 with 31 warnings.
-
Build passed.
Dojo Publication Decision
Do not publish existing generated .flowstate/dojo artifacts. Rebuild from this reviewed skillset after the auth isolation risks are fixed or formally tracked.
Usage
Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-mcp-gateway/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.
Install
Run this in your project to install via CLI:
fscloud dojo skill install flowstate-epic-flowstate-community-epicdm-flowstate-mcp-gateway --target <target> --out ./skillsReplace <target> with your agent target identifier. See the CLI docs for details.