# Reported issues for workflows-mcp-server

Pod holds 17 of 19 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [workflows-mcp-server](/mcp/workflows-mcp-server).

## Most discussed

### docs(readme): document versioned workflow filenames

### Use case

The README's `workflow_create` section describes the permanent workflow path without the version segment, but the implementation writes versioned filenames so multiple versions can coexist. The docs should match the current storage behavior.

### Proposed behavior

Update the README bullet under `workflow_create` from:

```text
categories/<slugified-category>/<slugified-name>-workflow.yaml
```

to the actual shape:

```text
categories/<slugified-category>/<slugified-name>-<slugifie

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/14) · 2026-07-01 · closed · 1 comment

### feat(tool-defs): tighten client-facing workflow descriptions and empty-list context

The current tool catalog works, but several descriptions expose implementation details or coach the reader instead of describing the API surface. Tightening these strings would make `tools/list` easier for clients to use and reduce accidental coupling to local file layout.

## Proposal

Revise the tool descriptions, parameter descriptions, output descriptions, and empty-result text to be behavior-oriented and client-facing. Keep details that directly affect caller behavior, but avoid implementat

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/13) · 2026-07-01 · closed · 1 comment

### bug(seed): bundled research visualization workflow is missing category metadata

### Server version

0.1.2

### mcp-ts-core version

0.10.6

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

stdio

### OS

macOS 26.1

### Description

The bundled permanent workflow at `workflows-yaml/categories/research-visualization/pubmed-research-with-cosmograph-visualization-workflow.yaml` has no `category:` field. Startup logs a warning for it, and category-filtered `workflow_list` calls cannot match it by category even though it lives under a category directory.

### St

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/12) · 2026-07-01 · closed · 1 comment

### bug(config): missing WORKFLOWS_DIR leaves watcher and snapshot disabled

### Server version

0.1.2

### mcp-ts-core version

0.10.6

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

When `WORKFLOWS_DIR` points at a directory that does not exist yet, startup continues and the server reports ready, but the filesystem watcher exits immediately and `_index.json` cannot be written. This can happen on first-run installs where users have not created the workflow root before starting the server.

#

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/11) · 2026-07-01 · closed · 1 comment

### bug(workflow_create): categories that slugify empty write into categories root

### Server version

0.1.2

### mcp-ts-core version

0.10.6

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`workflow_create` rejects whitespace-only categories, but it does not reject categories that contain no slug-safe characters. A category like `!!!` passes validation, slugifies to an empty string, and writes the workflow directly under `categories/` rather than under a category directory.

### Steps to reproduce

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/10) · 2026-07-01 · closed · 1 comment

### bug(validation): invalid semver strings can crash latest workflow lookup

### Server version

0.1.2

### mcp-ts-core version

0.10.6

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

The version schema accepts strings that start with `x.y.z` but are not valid semver, such as `1.0.0junk`. Once an invalid version is indexed alongside a valid version of the same workflow, `workflow_get` without an explicit version calls `semver.rcompare` and returns an internal error instead of a workflow or va

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/9) · 2026-07-01 · closed · 1 comment

### bug(workflow_create): hand-written YAML can make created workflows disappear from the index

### Server version

0.1.2

### mcp-ts-core version

0.10.6

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`workflow_create` and `workflow_create_temp` build YAML by hand. Some valid string inputs are emitted as unquoted YAML scalars or unescaped mapping keys, so the tool reports `status: "created"` even though the next index rebuild rejects or cannot parse the file.

### Steps to reproduce

Case 1: scalar coercion

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/8) · 2026-07-01 · closed · 1 comment

### bug(workflow_create): duplicate name@version can overwrite index across categories

### Server version

0.1.2

### mcp-ts-core version

0.10.6

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`workflow_create` says it rejects an existing `name@version`, but the current duplicate guard only catches the same destination filename. Creating the same `name` and `version` under a different category writes a second file successfully, then the index collapses both files to one key with last-write-wins behavi

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/7) · 2026-07-01 · closed · 1 comment

## Most recent

### feat(config): default MCP_SESSION_MODE to stateless across env, Docker, and src

`Dockerfile` sets `ENV MCP_SESSION_MODE="stateless"`, but `.env.example` sets `MCP_SESSION_MODE=auto` (uncommented). The container and the same code run via `bunx`, `npm start`, or from source therefore resolve to different session modes — stateless in Docker, stateful everywhere else, since the framework schema defaults to `auto` and `auto` resolves to `stateful`.

Related: cyanheads/mcp-ts-core#376

## Proposal

Make stateless this server's single, explicit default across every surface, so the

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/23) · 2026-08-22 · open · 0 comments

### bug(index): temporary entries shadow permanent workflows with the same key

### Server version

0.2.0

### mcp-ts-core version

0.10.10

### Runtime

Bun

### Runtime version

Bun 1.3.14

### Transport

HTTP (Streamable HTTP)

### Description

A temporary and permanent workflow can share the same `name@version`. The rebuild scans permanent files first and temporary files second into one `Map`, so the temporary entry replaces the permanent entry. The permanent file remains on disk but disappears from `workflow_list`, `workflow_get` returns the temp copy, and `workflow_de

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/19) · 2026-07-16 · open · 0 comments

### bug(validation): create tools accept whitespace-only workflow content

### Server version

0.2.0

### mcp-ts-core version

0.10.10

### Runtime

Bun

### Runtime version

Bun 1.3.14

### Transport

HTTP (Streamable HTTP)

### Description

`workflow_create`, `workflow_create_temp`, and the index schema use `z.string().min(1)` for several meaningful fields. Whitespace-only descriptions, authors, step server names, and step tool names therefore pass validation, are written to disk, and remain indexed. The permanent tool already applies a semantic whitespace check to `

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/22) · 2026-07-16 · open · 0 comments

### bug(temp): temporary workflows persist across sessions with no expiry path

### Server version

0.2.0

### mcp-ts-core version

0.10.10

### Runtime

Bun

### Runtime version

Bun 1.3.14

### Transport

HTTP (Streamable HTTP)

### Description

The public surface describes temporary workflows as session-scoped, short-lived, and self-expiring, but `workflow_create_temp` writes ordinary YAML files and startup re-indexes every file under `temp/`. There is no expiry metadata, cleanup, or delete path, so temporary workflows persist indefinitely while `workflow_delete` refuses

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/18) · 2026-07-16 · open · 0 comments

### feat(workflow_create_temp): report overwrite outcomes with output-path parity

### Server version

0.2.0

### mcp-ts-core version

0.10.10

### Runtime

Bun

### Runtime version

Bun 1.3.14

### Transport

HTTP (Streamable HTTP)

### Use case

`workflow_create_temp` documents overwrite semantics, but every call returns `status: "created"` even when it replaced an existing draft. Its `content[]` output also adds a temporary-workflow notice that is absent from `structuredContent`, so clients consuming the two MCP result paths do not receive the same complete result context.

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/20) · 2026-07-16 · open · 0 comments

### bug(storage): slug-derived filenames collide for distinct workflow keys

### Server version

0.2.0

### mcp-ts-core version

0.10.10

### Runtime

Bun

### Runtime version

Bun 1.3.14

### Transport

HTTP (Streamable HTTP)

### Description

Workflow identity is `name@version`, but file identity is built from lossy slugs of both fields. Distinct valid keys can therefore map to one path. Permanent creation misreports the second distinct key as already existing; temporary creation silently overwrites the first file and removes that version from the index.

Related: #7, 

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/21) · 2026-07-16 · open · 0 comments

### feat(workflow_delete): require explicit confirmation for destructive deletes

### Use case

`workflow_delete` is marked `destructiveHint: true`, but the handler deletes immediately without an elicitation/confirmation step. A call that omits `version` also deletes the highest available version immediately, which is documented behavior from #5 but still a high-blast-radius default for an irreversible operation. A confirmation gate protects any client (or agent-driven call) from an accidental or under-specified delete before the file is unlinked.

Related: #5

## Proposal

A

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/17) · 2026-07-03 · open · 0 comments

### bug(validation): validate workflow_get and workflow_delete version inputs as semver

### Server version

0.2.0

### mcp-ts-core version

0.10.10

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`workflow_get` and `workflow_delete` describe `version` as a semver string, but their input schemas accept any string. Invalid versions like `not-semver` reach the service lookup path and return `not_found` / `version_not_found`, which misclassifies bad input as a missing workflow.

### Steps to reproduce

1. C

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/16) · 2026-07-03 · open · 0 comments

### bug(workflow_list): trim filter values before matching

### Server version

0.2.0

### mcp-ts-core version

0.10.10

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`workflow_list` checks `query?.trim()` / `category?.trim()` to decide whether a filter is present, but then matches with the original untrimmed string. Accidental leading or trailing whitespace makes otherwise-valid query, category, and tag filters return zero results.

### Steps to reproduce

1. Start the serv

[Read the thread](https://github.com/cyanheads/workflows-mcp-server/issues/15) · 2026-07-03 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/cyanheads/workflows-mcp-server/issues).