Migrate all repos into monorepo context folders
Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp,
Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit,
Projekt-KIQ-HP, teamlandkarte-mcp
Dhive: Jury-Voting
Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation)
Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more
Shared/references: symphony (read-only)
Bahn repos remain available as independent remotes - this monorepo
pulls them in via subtree, the originals are untouched.
This commit is contained in:
@@ -0,0 +1,227 @@
|
||||
# Troubleshooting
|
||||
|
||||
## The server fails at startup with `Missing config.toml`
|
||||
|
||||
- Copy the template and fill in non-secret settings:
|
||||
- `cp config.toml.example config.toml`
|
||||
- Ensure `--config` points to the correct file when starting the server.
|
||||
|
||||
## Database connectivity problems
|
||||
|
||||
Symptoms:
|
||||
|
||||
- `DatabaseError: Trino error: ...`
|
||||
|
||||
Checklist:
|
||||
|
||||
1. Verify host/port in `config.toml`.
|
||||
2. Verify username/password.
|
||||
3. Verify TLS settings: `http_scheme` and `verify_ssl`.
|
||||
4. Ensure `database.backend = "trino"`.
|
||||
5. Run the smoke check script: `scripts/trino_smoke_check.py`.
|
||||
|
||||
## Confirmation gate blocks matching
|
||||
|
||||
Symptoms:
|
||||
|
||||
- A matching tool refuses to run and tells you to confirm requirements.
|
||||
|
||||
Explanation:
|
||||
|
||||
- Requirement capture tools write **pending** requirements.
|
||||
- When `matching.require_confirmation = true` (default), matching tools require an explicit user confirmation flow.
|
||||
|
||||
Additional note (multi-client environments):
|
||||
|
||||
- Pending/confirmed state is stored in an in-memory server session.
|
||||
- If multiple clients share one server process, confirmation state can become
|
||||
ambiguous. In such setups, enforce the confirmation workflow strictly on the
|
||||
client/agent side.
|
||||
|
||||
Fix (recommended sequence):
|
||||
|
||||
1. Capture/update requirements (e.g. `extract_requirements`, `collect_structured_requirement_data`, `update_requirements`, guided tools).
|
||||
2. Call `show_pending_requirements()` (review table) **after the last update**.
|
||||
3. Ask the user to confirm (Yes/No).
|
||||
4. Call `confirm_requirements(confirm=true)`.
|
||||
5. Re-run the matching tool.
|
||||
|
||||
Optional (dev/testing):
|
||||
|
||||
- Set `matching.require_confirmation = false` in `config.toml` to auto-skip confirmation.
|
||||
|
||||
## confirm_requirements was called but matching is still blocked
|
||||
|
||||
Symptoms:
|
||||
|
||||
- The assistant called `confirm_requirements(confirm=true)` but matching tools still refuse to run.
|
||||
|
||||
Explanation:
|
||||
|
||||
- The workflow is two-step: the assistant must first request user confirmation.
|
||||
- The recommended sequence is:
|
||||
1. `show_pending_requirements()` (review table)
|
||||
2. Ask the user to confirm (Yes/No)
|
||||
3. `confirm_requirements(confirm=true)`
|
||||
|
||||
Fix:
|
||||
|
||||
- If requirements were updated after the review step, you must re-run `show_pending_requirements()` and ask the user again.
|
||||
- Then call `confirm_requirements(confirm=true)`.
|
||||
|
||||
## Guided capture feels stuck
|
||||
|
||||
Guided capture is step-based. Call the tools in order:
|
||||
|
||||
1. `start_guided_capture()`
|
||||
2. `guided_set_description(...)`
|
||||
3. `guided_set_role(...)`
|
||||
4. `guided_set_time_range(date_start?, date_end?)` (open-ended ranges are allowed)
|
||||
5. `guided_set_competences([...])`
|
||||
6. `show_pending_requirements()`
|
||||
7. Ask the user to confirm (Yes/No)
|
||||
8. `confirm_requirements(confirm=true)`
|
||||
|
||||
## "Unknown or expired search_id" (or filters/pagination stop working)
|
||||
|
||||
Symptoms:
|
||||
|
||||
- `get_results_by_category(...)` or `filter_search_results(...)` returns an error.
|
||||
- Newer server versions also return a machine-readable status:
|
||||
- `META.status=unknown_or_expired`
|
||||
|
||||
Common causes:
|
||||
|
||||
1. **TTL expiry**: the search results cache is time-limited.
|
||||
- Controlled by `cache.search_ttl_minutes`.
|
||||
2. **Eviction due to cache size**: the cache is LRU and bound by `cache.max_size`.
|
||||
- If many searches are started, older `search_id`s can be evicted even within TTL.
|
||||
3. **Process mismatch / restart**: in-memory caches are per server process.
|
||||
- If the server restarts, or the client routes to a different instance, old `search_id`s are not available.
|
||||
4. **Copy hygiene**: some chat UIs add backticks or whitespace.
|
||||
- Prefer copying the UUID from the tool output header line `SEARCH_ID=<uuid>`.
|
||||
- Do not include backticks, quotes, or extra whitespace.
|
||||
|
||||
Fix:
|
||||
|
||||
- Re-run the matching tool to create a new `search_id`.
|
||||
- Increase `cache.search_ttl_minutes` and/or `cache.max_size` for longer interactive sessions.
|
||||
- Ensure your MCP client uses a single long-lived server process.
|
||||
|
||||
## "Invalid search_id format (expected UUID)"
|
||||
|
||||
Cause:
|
||||
|
||||
- The server validates `search_id` inputs and rejects anything that is not a UUID.
|
||||
|
||||
Fix:
|
||||
|
||||
- Copy the value from the most recent tool output header:
|
||||
- `Using SEARCH_ID=<uuid>` (first line)
|
||||
- or `SEARCH_ID=<uuid>`
|
||||
|
||||
## Search tool output parsing (Cherry Studio / chat UI issues)
|
||||
|
||||
Search-related tools emit deterministic headers (intended to be parsed verbatim):
|
||||
|
||||
- First line marker:
|
||||
- `Using SEARCH_ID=<uuid>`
|
||||
- Machine-readable headers:
|
||||
- `SEARCH_ID=<uuid>`
|
||||
- `FILTER_ID=<uuid>` (if applicable)
|
||||
- `META=<json>`
|
||||
|
||||
Output shape notes:
|
||||
|
||||
- Only `find_matching_capacities` includes the category-count `## Summary` table.
|
||||
- `filter_search_results` includes an **Applied Filters** table and a flat results table with a `Category` column (it does not reprint the summary counts).
|
||||
- `get_results_by_category` returns a single category-page table (it does not reprint the summary counts).
|
||||
|
||||
If your UI hides tool output:
|
||||
|
||||
- Re-run the tool call, or
|
||||
- manually copy the UUID from the server output and paste it without formatting.
|
||||
|
||||
## "No matches" or unexpectedly few matches
|
||||
|
||||
- Confirm the required competences list is not over-specific.
|
||||
- Confirm role name is reasonable (role similarity affects scoring).
|
||||
- If you supplied date filters, remember availability is filter-only:
|
||||
- capacities must overlap the requested range
|
||||
- open-ended capacity `end_date` is treated as available without limit
|
||||
|
||||
## Debug logging
|
||||
|
||||
Start the server with:
|
||||
|
||||
- `--log-level DEBUG`
|
||||
|
||||
The database clients emit safe query logs (SQL is normalized; parameters are redacted).
|
||||
|
||||
## Cherry Studio: stdio "connection closed" / tools not listing
|
||||
|
||||
Common causes:
|
||||
|
||||
- The server writes logs to stdout (breaks JSON-RPC). This project logs to
|
||||
**stderr**.
|
||||
- Cherry cannot set a working directory, so `uv run` cannot find the project.
|
||||
|
||||
Workaround (wrap with `zsh -lc`):
|
||||
|
||||
- `zsh -lc 'cd /Users/thomashandke/ws/teamlandkarte-mcp && uv run python -m teamlandkarte_mcp --config /Users/thomashandke/ws/teamlandkarte-mcp/config.toml --log-level DEBUG'`
|
||||
|
||||
Also ensure your `PATH` contains your `uv`/`uvx` directory, e.g.
|
||||
`/Users/thomashandke/.local/bin`.
|
||||
|
||||
## Azure OpenAI API Errors
|
||||
|
||||
Symptoms:
|
||||
|
||||
- Tools that compute similarity fail with `AzureAPIError`.
|
||||
|
||||
Common causes and fixes:
|
||||
|
||||
1. **Missing credentials**
|
||||
- Ensure the environment variable is set:
|
||||
- `AZURE_OPENAI_EMBEDDING_API_KEY`
|
||||
- If you rely on `.env`, confirm it is loaded in the shell that starts the MCP
|
||||
server.
|
||||
|
||||
2. **Invalid endpoint / deployment**
|
||||
- Check `[azure_openai].endpoint` in `config.toml` (must be your Azure OpenAI
|
||||
resource endpoint).
|
||||
- Check `embedding_deployment` exists in Azure and matches your deployment.
|
||||
|
||||
3. **Rate limits / throttling (HTTP 429)**
|
||||
- Retry later.
|
||||
- Reduce concurrency in the client/agent.
|
||||
- Use the embedding cache to reduce repeated embedding calls.
|
||||
|
||||
4. **Network / TLS / proxy issues**
|
||||
- Try `curl` to the Azure endpoint from the same host.
|
||||
- If you are behind a corporate proxy, ensure the environment is configured
|
||||
accordingly.
|
||||
|
||||
Debugging tips:
|
||||
|
||||
- Start the server with `--log-level DEBUG` and look at stderr logs.
|
||||
- Confirm your `config.toml` is the one the server loads (`--config ...`).
|
||||
|
||||
## MCP sampling / embedding features
|
||||
|
||||
This server uses **Azure OpenAI embeddings** for embedding-based similarity
|
||||
scoring.
|
||||
|
||||
- Ensure `AZURE_OPENAI_EMBEDDING_API_KEY` is set.
|
||||
- Ensure `[azure_openai]` in `config.toml` points to a valid Azure OpenAI endpoint.
|
||||
|
||||
## IDE shows "line too long (.. > 79)" but Ruff passes
|
||||
|
||||
Some editor integrations (or their default settings) may enforce a 79 character
|
||||
line length even if the repository uses a different limit.
|
||||
|
||||
If `uv run ruff check` passes but the editor still flags lines:
|
||||
|
||||
- Prefer the repo result as the source of truth.
|
||||
- Adjust your editor/extension settings (Python/Ruff/Flake8) to match the
|
||||
project configuration.
|
||||
Reference in New Issue
Block a user