dsh-tool-jira
A Cordis tool plugin that gives DeepSeek Harness (dsh) Jira issue management capabilities. Agents can search JQL queries, find users, inspect projects, issue types, and priorities, create and update tickets, add comments, and move issues through workflow transitions.
It follows the official "everything is a plugin" architecture with ctx.tools.register(defineTool(...)) and the adding-a-tool contract.
Install
Install directly from GitHub:
npm install github:LJH-snow/dsh-tool-jiraOr from a local checkout:
git clone https://github.com/LJH-snow/dsh-tool-jira
cd dsh-tool-jira
npm install && npm run build
npm install /path/to/dsh-tool-jiraRequires @deepseek-ai/cordis (^4.0.1) and @deepseek-ai/dsh-tools (^0.1.0-rc.6) as peer dependencies, provided by the host dsh runtime.
Configuration
Load the plugin in a dsh composition config (cordis.yml):
- name: 'github:LJH-snow/dsh-tool-jira'
config:
baseUrl: 'https://your-domain.atlassian.net' # required
email: 'user@example.com' # required for Cloud API token auth
apiToken: 'xxx' # Atlassian API token or PAT
timeoutMs: 15000 # optional, default 15000Full example: examples/cordis.yml.
Security: the first version requires credentials for every tool because Jira instances are usually access-controlled and write operations can modify tickets. Use an API token or PAT with the minimum permissions needed, and never commit it.
Tools
| Tool | Description | Credentials |
|---|---|---|
jira_search_issues |
Search issues with JQL, up to 100 results | yes |
jira_search_my_issues |
Search issues assigned to the authenticated user | yes |
jira_get_issue |
Get issue details including ADF description text | yes |
jira_create_issue |
Create an issue with summary, type, description, labels, priority, and assignee | yes |
jira_update_issue |
Update summary, description, labels, priority, or assignee | yes |
jira_add_issue_comment |
Add a comment to an issue | yes |
jira_list_issue_comments |
List issue comments, newest first | yes |
jira_list_transitions |
List workflow transitions available for an issue | yes |
jira_transition_issue |
Move an issue through a workflow transition | yes |
jira_list_projects |
List projects visible to the authenticated user | yes |
jira_get_project |
Get project details including description, lead, type, style, and archived state | yes |
jira_list_issue_types |
List issue types visible to the authenticated user, including subtask flags | yes |
jira_list_priorities |
List priorities with descriptions and status color | yes |
jira_search_users |
Search users by display name, username, or email to get Atlassian account ids | yes |
jira_get_user |
Get one user by account id, including display name, email, active state, and time zone | yes |
Behavior Contract
- Missing credentials return canonical business values: read tools return
{ authenticated: false, ... }, write tools return{ ok: false, reason }or{ created: false, reason }. - Missing issue, project, or user maps to
{ found: false }. - Write validation failures (400, 404, 422) map to
{ ok: false, reason }or{ created: false, reason }. - Infrastructure errors such as invalid credentials (401), forbidden access (403), or rate limiting (429) throw.
- Every request forwards
exec.signaland uses a configurable timeout (default 15 seconds).
Development
npm install
npm run typecheck
npm test
npm run buildSee DEVELOPMENT.md for the architecture and test coverage.