# 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](/mcp/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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/256) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/258) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/241) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/672) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/444) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/218) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/255) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/443) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/704) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/671) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/673) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/669) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/670) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/664) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/666) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/667) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/668) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/665) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/662) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/661) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/663) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/657) · 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](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/656) · 2026-08-12 · open · 1 comment

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