Reported issues for Waggle-mcp

Pod holds 23 of 267 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 Waggle-mcp.

Most discussed

docs: add a Troubleshooting section to README for common errors

Problem

When something goes wrong on first install — wrong Python version, missing system deps, model download failures, port conflicts — users get a raw Python traceback and no pointer to where to look. A Troubleshooting section in the README would save dozens of new-user issues.

What to do

Add a ## Troubleshooting section at the bottom of README.md (right before any final acknowledgements section). Cover the five most common failure modes:

1. **`ModuleNotFoundError: No module nam

Read the thread · 2026-06-04 · open · 11 comments

bug: source files contain print() statements that should be logger calls

Problem

Five source files in src/waggle/ contain print() statements:

• src/waggle/server.py
• src/waggle/rlm.py
• src/waggle/hooks/claude_code/pre_compact.py
• src/waggle/hooks/claude_code/pre_response.py
• src/waggle/hooks/claude_code/post_response.py

For production code, print() is the wrong tool: it bypasses the JSON log formatter, breaks the runtime context attribution (tenant_id, request_id, etc.), and corrupts the MCP stdio transport when it goes to stdout.

What t

Read the thread · 2026-06-04 · open · 10 comments

test: add tests for graph_ui.render_graph_editor_html

Problem

src/waggle/graph_ui.py::render_graph_editor_html (lines 7-43) produces the HTML shell that loads Graph Studio. It has no tests. A regression in mode handling, asset versioning, or config injection would silently break the UI.

What to do

Create tests/test_graph_ui.py covering:

1. Default mode is "edit". Calling with no mode arg produces HTML containing "mode": "edit".
2. "view" mode is honored. mode="view" produces "mode": "view".
3. Mode normalization. `

Read the thread · 2026-06-04 · open · 9 comments

test(config): cover invalid boolean environment values

Goal\nAdd a focused test for an invalid boolean environment value and assert the resulting configuration error identifies the variable.\n\n## Suggested files\n- tests/test_config.py, src/waggle/config.py\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 8 comments

docs(graph): add a code-aware memory how-to with a pasted-code example

Summary

observe_conversation now extracts functions/classes from fenced code blocks and links them as ENTITY nodes (#419). A worked example would help contributors and users.

Task

• Add an example to docs/reference.md showing a turn that contains a fenced ```python code block and the resulting code-entity node(s) + links.
• Note the optional code-analysis extra (tree-sitter) and the regex fallback.

Acceptance criteria

• Docs only; example reflects actual behavior.

Read the thread · 2026-06-22 · open · 8 comments

docs: add a 'How Waggle saves tokens' explainer page

Problem

New users and contributors don't have a clear mental model of why persistent graph memory reduces token usage compared to stuffing raw conversation history into every prompt. A short explainer page would bridge that gap and give context for the token benchmark work (#214).

What to do

Create docs/how-waggle-saves-tokens.md that explains:

1. The problem: LLMs have fixed context windows. Without memory, every turn must re-include prior conversation history. As conversations

Read the thread · 2026-06-01 · open · 8 comments

perf: lazy-import sentence-transformers and torch only when needed

Problem

sentence-transformers (and the torch it pulls in) is the slowest import in the whole codebase. Cold start of waggle-mcp is dominated by it, even when the user has set WAGGLE_MODEL=deterministic and never touches the real model.

We already lazy-load the model itself, but the imports happen at module level (or close to it). Every CLI invocation eats the import cost.

What to do

Audit imports of these three packages and push them down to function-local imports wherever they

Read the thread · 2026-06-04 · open · 7 comments

feature(graph-ui): add a legend for community colors and edge-confidence styles

Summary

Graph Studio now colors nodes by community and renders weak edges dashed/faded (#419), but there is no legend explaining the colors or line styles.

Task

• Add a small legend panel (or inline key) in Graph Studio that, in community color mode, lists cluster colors, and always shows the edge-confidence styles (explicit / inferred / weak).
• Keep it unobtrusive and consistent with the existing panel styling.

Acceptance criteria

• Legend appears in apps/mcp/graph-ui; `npm run bu

Read the thread · 2026-06-22 · open · 6 comments

Most recent

[bug] ImportError: cannot import name 'request_ctx' from mcp.server.lowlevel.server on fresh install (waggle-mcp 0.0.1, mcp 2.1.1)

Summary

Running waggle --help immediately after a fresh pip install crashes with an ImportError. waggle/server.py imports request_ctx from mcp.server.lowlevel.server, but this name does not exist in mcp 2.1.1, the version currently resolved by pip when installing waggle-mcp. The CLI is completely unusable out of the box for new users.

Steps to reproduce

1. pip install waggle-mcp
2. waggle --help
3. Observe ImportError instead of the expected help output

Expected behavior

Read the thread · 2026-08-28 · open · external user · 1 comment

docs(errors): add troubleshooting links for common errors

Goal\nAdd a compact mapping from a few common validation or connection errors to the relevant setup or security documentation.\n\n## Suggested files\n- docs/install/troubleshooting.md\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 3 comments

docs(repository): add test-directory navigation note

Goal\nAdd a short guide to the test-directory conventions, including where protocol, graph, and integration tests live.\n\n## Suggested files\n- docs/repository-map.md\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 5 comments

docs(extensions): add extension compatibility table

Goal\nAdd a small table linking each supported editor or client to its setup page and supported transport mode.\n\n## Suggested files\n- docs/install/README.md\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 3 comments

test(logging): cover newline-safe structured fields

Goal\nAdd coverage for a structured log field containing newlines and assert the emitted record remains parseable and does not create extra log entries.\n\n## Suggested files\n- tests/test_logging_utils.py, src/waggle/logging_utils.py\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 5 comments

docs(rlm): add a local Ollama setup example

Goal\nAdd a minimal local Ollama configuration example that names the required model setting and expected command shape.\n\n## Suggested files\n- README.md or src/rlm documentation\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 1 comment

docs(deployment): explain SQLite backup expectations

Goal\nAdd a short section explaining what SQLite files should be backed up, when to stop writes, and where to find the existing restore guidance.\n\n## Suggested files\n- docs/deployment/production.md\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 3 comments

test(cli): cover help output for a maintenance command

Goal\nChoose one existing maintenance subcommand and add a focused test confirming --help exits successfully and includes its key option.\n\n## Suggested files\n- tests/test_server.py or relevant CLI tests\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · closed · 2 comments

docs(security): link threat model from install docs

Goal\nAdd one clear link from installation guidance to the security model so self-hosting users can find the trust-boundary assumptions.\n\n## Suggested files\n- docs/install/README.md, docs/security/security-model.md\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 2 comments

test(auth): cover whitespace-only API key input

Goal\nAdd a validation regression test for whitespace-only API key input and assert it is rejected consistently.\n\n## Suggested files\n- tests/test_auth.py, src/waggle/auth.py\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 4 comments

tooling(markdown): ignore fenced code blocks in link checks

Goal\nAdd test coverage proving URL-like text inside fenced code blocks is not treated as a documentation link to validate.\n\n## Suggested files\n- scripts/check_markdown_links.py, tests\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 2 comments

tooling(labels): test unknown-label handling

Goal\nAdd a unit test that an unknown or malformed label entry produces a clear validation message rather than silently being skipped.\n\n## Suggested files\n- tests/test_label_sync_script.py, scripts/sync_github_labels.py\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 1 comment

docs(rlm): add environment-variable quick reference

Goal\nAdd a compact table for the most common RLM environment variables and a link to the fuller configuration documentation.\n\n## Suggested files\n- README.md or src/rlm documentation\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 1 comment

docs(project-memory): add a session-scope CLI example

Goal\nAdd one complete session-scope command example with project and session identifiers, plus a short explanation of the output.\n\n## Suggested files\n- docs/project-memory-cli.md\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 2 comments

docs(vscode): clarify local versus remote workspace setup

Goal\nExplain the difference between configuring Waggle for a local VS Code workspace and a remote development workspace.\n\n## Suggested files\n- docs/install/vscode.md\n\n## Acceptance criteria\n- The change stays focused on the stated scope.\n- Documentation or tests are updated as appropriate.\n- The relevant focused test or documentation validation passes.\n\nThis is intentionally scoped as a starter contribution.

Read the thread · 2026-08-12 · open · 1 comment

The remaining reports are on the project's issue tracker.