97 lines
5.1 KiB
Markdown
97 lines
5.1 KiB
Markdown
---
|
|
inclusion: always
|
|
---
|
|
|
|
# Factbase MCP Bug Reporting and Feature Requests
|
|
|
|
## When to File a Bug
|
|
|
|
Whenever you use any `mcp_factbase_*` tool and encounter ANY of the following, you MUST submit a task to the Vikunja board:
|
|
|
|
- **Errors**: MCP errors, panics, internal errors, timeouts, or unexpected exceptions
|
|
- **Unexpected results**: Tool returns success but the output is wrong, incomplete, or nonsensical
|
|
- **Data corruption**: Documents modified incorrectly, content lost, formatting broken after an operation
|
|
- **Silent failures**: Tool claims success but nothing actually changed (e.g. apply_review_answers says it applied N answers but files are unchanged)
|
|
- **Missing functionality**: A tool doesn't behave as its description says it should
|
|
- **Performance issues**: Operations that take unreasonably long or hang
|
|
|
|
Do NOT wait for the user to ask you to file a bug. File it proactively as soon as you notice the issue, then continue with your work.
|
|
|
|
## How to File
|
|
|
|
```
|
|
curl -X PUT https://vikunja.home.everyonce.com/api/v1/projects/2/tasks \
|
|
-H "Authorization: Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"title": "[factbase] <short bug summary>",
|
|
"description": "<detailed description including:\n- Which MCP tool was called\n- What parameters were passed\n- What the expected behavior was\n- What actually happened (include error message if any)\n- Any workaround used>",
|
|
"priority": 3
|
|
}'
|
|
```
|
|
|
|
### Priority Guide
|
|
- **1-2**: Minor cosmetic issues, suggestions for improvement
|
|
- **3**: Normal bugs — tool errors, unexpected behavior
|
|
- **4**: Significant bugs — data loss, corruption, tools that are completely broken
|
|
- **5**: Urgent — blocking all factbase operations
|
|
|
|
### API Details
|
|
- Base URL: `https://vikunja.home.everyonce.com/api/v1`
|
|
- Auth: `Authorization: Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8`
|
|
- Project ID: 2 (OpenClaw Tasks)
|
|
- Tasks land in the To-Do bucket (id: 4) by default
|
|
|
|
### Check Task Status
|
|
|
|
```
|
|
# Get a specific task
|
|
curl https://vikunja.home.everyonce.com/api/v1/tasks/<task_id> \
|
|
-H "Authorization: Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8"
|
|
|
|
# List all tasks in the project
|
|
curl "https://vikunja.home.everyonce.com/api/v1/projects/2/tasks" \
|
|
-H "Authorization: Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8"
|
|
```
|
|
|
|
A task is complete when `"done": true`.
|
|
|
|
### Kanban Buckets
|
|
- Backlog (7) — queued, not yet started
|
|
- To-Do (4) — ready for work ← tasks land here by default
|
|
- Doing (5) — in progress
|
|
- Done (6) — completed
|
|
|
|
### Rules
|
|
- Always prefix task titles with `[factbase]`
|
|
- Include enough detail in the description to reproduce the bug
|
|
- Don't assign — the local dev agent picks up and runs tasks automatically
|
|
- Mention the agent session context briefly (e.g. "while running LinkedIn discovery workflow" or "during factbase review answer application")
|
|
- If you worked around the issue, describe the workaround in the description
|
|
|
|
## When to File a Feature Request
|
|
|
|
Beyond bugs, you should ALSO proactively file feature requests when you notice friction, gaps, or missed opportunities while using factbase. Specifically:
|
|
|
|
- **Missing MCP tools**: CLI commands that exist but aren't exposed via MCP (e.g. `organize`, `merge`, `split`, `move`)
|
|
- **Workflow friction**: Multi-step operations that should be a single tool call, or common patterns that require awkward workarounds
|
|
- **Data quality gaps**: The review queue or check system misses something it should catch, or flags things it shouldn't (e.g. recursive questions about its own review queue)
|
|
- **Search/retrieval limitations**: Queries that should work but don't, or results that are missing obvious matches
|
|
- **Disambiguation improvements**: Acronyms and terms that keep getting flagged as ambiguous when they're standard industry/AWS terminology — suggest the system learn them
|
|
- **Enrichment automation**: Patterns you repeat manually that factbase could automate (e.g. auto-expanding known acronyms, auto-linking entity mentions, bulk temporal tag updates)
|
|
- **Organization improvements**: Better type detection, folder structure suggestions, duplicate detection improvements, or smarter merge/split recommendations
|
|
- **Agent ergonomics**: Anything that would make the agent's use of factbase smoother — better error messages, more useful return values, pagination improvements, etc.
|
|
|
|
File these the same way as bugs, but use priority 1-2 and prefix with `[factbase][feature]`:
|
|
|
|
```
|
|
$headers = @{ "Authorization" = "Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8"; "Content-Type" = "application/json" }
|
|
$body = '{"title":"[factbase][feature] <short feature summary>","description":"<what the feature would do, why it matters, example use case>","priority": 2}'
|
|
Invoke-RestMethod -Method Put -Uri "https://vikunja.home.everyonce.com/api/v1/projects/2/tasks" -Headers $headers -Body $body
|
|
```
|
|
|
|
### Feature Request Priority
|
|
- **1**: Nice-to-have, low impact — cosmetic or minor convenience
|
|
- **2**: Meaningful improvement — reduces friction, saves time, improves data quality
|
|
- **3**: Important gap — blocking a common workflow or causing repeated manual workarounds
|