Files

T

thanhnvandClaude Opus 5 42f4a058ea feat(jira-knowledge): add contextual help tooltips and inline validation for Project Mapping

- Add QToolButton help icon (?) next to Project Mapping label
- Implement comprehensive tooltip explaining Project ID and Jira Key concepts
- Add inline validation to detect common mistake: entering issue keys (ABC-123) instead of project keys (ABC)
- Add 13 new i18n keys for help text in English, Vietnamese, and Japanese
- Add 15 comprehensive UX tests covering icon presence, tooltip content, validation logic, and accessibility
- Update jira-knowledge-guide.md with help icon reference and setup instructions
- Fix missing _on_paste method that was causing AttributeError

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-08 01:38:41 +09:00

5.5 KiB

Raw Blame History

Jira Project Knowledge - Production Guide

This guide covers the setup, operation, and troubleshooting of the Jira Project Knowledge capability in Cowork Local.

1. Architecture Overview

Jira Project Knowledge enables Cowork to index Jira issues as searchable project knowledge. The flow is:

Configuration: User maps a Cowork project to a Jira project key via UI.
Sync: JiraSyncService fetches issues from Jira using the configured credentials.
Normalization: Raw Jira JSON is converted to CanonicalJiraIssue (stripping markup, bounding content).
Indexing: Canonical issues are stored as atomic JSON files in ~/.cowork_local/jira_kb/<project_id>/issues/.
Retrieval: search_project_knowledge MCP tool queries the local index using lexical scoring.

2. Prerequisites

Jira Access: Read-only access to the target Jira project.
Credentials:
- Jira Cloud: Email + API Token (from id.atlassian.com).
- Jira Server/Data Center: Personal Access Token (PAT) or Username/Password.
Python: 3.10+ (for Pydantic v2 compatibility).

3. Setup & Configuration

3.1 Connect Jira

Open Cowork Local.
Go to Monitoring -> Tools -> Jira.
Enter Base URL (e.g., https://your-domain.atlassian.net or https://jira.company.com).
Enter Email (for Cloud) or Username (for Server).
Enter API Token or PAT.
Click Test Connection.

3.2 Enable Project Knowledge

In the same Jira dialog, check Enable Jira Project Knowledge.
Enter Project Mapping in the format cowork_project_id:JIRA_PROJECT_KEY.
- Example: proj-alpha:ALPHA, proj-beta:BETA
- Click the ⓘ icon next to "Project Mapping" for detailed help on:
  - Project ID: The Cowork project identifier (e.g., cowork-local). Find it in your current Cowork project settings.
  - Jira Key: The Jira project key (e.g., ALPHA from issue ALPHA-123). Open any Jira issue to find it.
- Common mistake: Do not enter issue keys like ABC-123. Only enter the project key part ABC.
Click Save.

3.3 Initial Sync

Click Sync Now.
Wait for the status to update to "Success: X issues synced".
The sync runs in the background; the UI remains responsive.

4. Usage

4.1 Search via Agent

Ask the agent questions about the project requirements or bugs. The agent will automatically use search_project_knowledge if Jira Knowledge is enabled for the current project.

Example: "What are the acceptance criteria for the login feature?"
Example: "Find bugs related to database timeout."

4.2 MCP Tool

The tool search_project_knowledge is available via the Project Context MCP server.

Input: project_id, query, top_k (optional).
Output: Ranked list of excerpts with Jira source URLs.

5. Security & Isolation

Read-Only: The connector never writes to Jira.
Project Isolation: Knowledge is strictly scoped by project_id. A user with access to Project A cannot search Project B's knowledge, even if they guess the project ID. The target resolver enforces this structurally.
Credential Safety: Credentials are stored in the OS Keyring (via SecretStore), not in plain text config files (unless fallback is used). They are never logged or sent to the LLM.
Untrusted Content: Jira content is treated as untrusted. Prompt injection attempts in Jira descriptions are fenced and neutralized before reaching the agent context.

6. Observability

Sync operations emit audit events to ~/.cowork_local/audit/YYYY-MM-DD.jsonl:

jira_knowledge.sync.started: Sync initiated.
jira_knowledge.sync.completed: Sync finished successfully (includes counts/duration).
jira_knowledge.sync.failed: Sync failed (includes error code).

7. Troubleshooting

403 Forbidden

Cause: Invalid credentials or insufficient permissions.
Fix:
- Cloud: Ensure you are using an API Token, not your password.
- Server: Ensure you are using a valid Personal Access Token (PAT). If PAT fails, try Basic Auth with your actual password (some older servers require this).
- Check that your user has "Browse Projects" permission for the target Jira project.

"Jira Project Knowledge is not configured"

Cause: No project mapping found for the current identity.
Fix: Ensure the cowork_project_id in the mapping matches the project selected in Cowork.

Sync Fails / Timeout

Cause: Network issues or large project size.
Fix: Check network connectivity to Jira. The sync has a timeout of 20s per request. For very large projects, the initial sync may take time; subsequent incremental syncs are faster.

8. File Structure

~/.cowork_local/config.json: Stores jira connection settings and jira_knowledge mappings.
~/.cowork_local/jira_kb/<project_id>/issues/: Indexed canonical issues (JSON).
~/.cowork_local/jira_kb/<project_id>/manifest.json: Sync state (last sync time, cursor).
~/.cowork_local/audit/: Audit logs.

9. Known Limitations

Lexical Search: Current retrieval uses term-overlap scoring, not semantic embeddings. It works well for exact terms and keywords but may miss conceptual synonyms.
Manual Sync: Incremental sync is not yet scheduled automatically; it must be triggered via "Sync Now" or CLI.
Rich Text: Complex Jira rich text (ADF) is simplified to plain text placeholders.

5.5 KiB Raw Blame History