Files

daniel 23098547f1 initial repo seedings

2026-02-22 21:35:29 +00:00

5.1 KiB

Raw Blame History

inclusion

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

5.1 KiB Raw Blame History