{"_id":"@aquarium-tools/shoal","_rev":"3-1997171aa415174e4f403399221705ce","name":"@aquarium-tools/shoal","dist-tags":{"latest":"1.1.0"},"versions":{"0.2.0":{"name":"@aquarium-tools/shoal","version":"0.2.0","keywords":["mcp","jira","atlassian","model-context-protocol"],"author":{"name":"Robert Ferguson"},"license":"Apache-2.0","_id":"@aquarium-tools/shoal@0.2.0","maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"homepage":"https://github.com/rmferguson/shoal#readme","bugs":{"url":"https://github.com/rmferguson/shoal/issues"},"bin":{"shoal":"dist/index.js"},"dist":{"shasum":"a8cce5addde9216c936f97d6c528575546f9192f","tarball":"https://registry.npmjs.org/@aquarium-tools/shoal/-/shoal-0.2.0.tgz","fileCount":99,"integrity":"sha512-IcNp47FSQfYuHuLKeQbsVQLEJqKGmGd4TwbM9emisdWBrNTvXNHmhu6CBvm24MBi2cfJFBor+Uiu5nn05gIBPA==","signatures":[{"sig":"MEUCIQCWM39E1Wm27d9sdThKE0l04afTA2yyNZRxSfjbbfvnXgIgLkiBbn7kxy3m7SXNnB2zDccMEPukwHpIaBXmOU9K7ao=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106921},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"gitHead":"3c5d806f04e33e7b7423de8d272ad32bfbc396b9","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"rm -rf dist && npm run build"},"_npmUser":{"name":"rmferguson","email":"rmferguson@pm.me"},"repository":{"url":"git+https://github.com/rmferguson/shoal.git","type":"git"},"_npmVersion":"10.9.2","description":"Jira MCP server — correct, complete, open source","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.2","@modelcontextprotocol/sdk":"^1.10.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","vitest":"^4.1.5","typescript":"^5.8.3","@types/node":"^22.15.3"},"_npmOperationalInternal":{"tmp":"tmp/shoal_0.2.0_1782972367154_0.08594382737132666","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@aquarium-tools/shoal","version":"1.0.0","keywords":["mcp","jira","atlassian","model-context-protocol"],"author":{"name":"Robert Ferguson"},"license":"Apache-2.0","_id":"@aquarium-tools/shoal@1.0.0","maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"homepage":"https://github.com/rmferguson/shoal#readme","bugs":{"url":"https://github.com/rmferguson/shoal/issues"},"bin":{"shoal":"dist/index.js"},"dist":{"shasum":"93984f0ec1ddd53ac00e556c3ccff829aebfa411","tarball":"https://registry.npmjs.org/@aquarium-tools/shoal/-/shoal-1.0.0.tgz","fileCount":99,"integrity":"sha512-ieAb96XpVtTY1HOUYTGfb86bo+7z9NvT6bCW9GTqGQK9/vZhMQGGL37fyuezh4UMmTRLIe+fCAYTSxZJhyuqZQ==","signatures":[{"sig":"MEQCIFBkQipwOb5cEZZE1V4U+hea0j+1phXSWtkwSfu66mT0AiAcUEiJdMAW9384eYBdSd4+kVyTCQ1JRfEfovK+Kfv0uA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aquarium-tools%2fshoal@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":106921},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"gitHead":"afa50f75b628fcf1a84bfd15cd6c53fb238d60c6","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"rm -rf dist && npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:77e52b07-0701-4324-9f5b-249b58f19913"}},"repository":{"url":"git+https://github.com/rmferguson/shoal.git","type":"git"},"_npmVersion":"11.18.0","description":"Jira MCP server — correct, complete, open source","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^3.24.2","@modelcontextprotocol/sdk":"^1.10.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","vitest":"^4.1.5","typescript":"^5.8.3","@types/node":"^22.15.3"},"_npmOperationalInternal":{"tmp":"tmp/shoal_1.0.0_1782972538240_0.6394218811426862","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aquarium-tools/shoal","version":"1.1.0","description":"Jira MCP server — correct, complete, open source","type":"module","main":"dist/index.js","bin":{"shoal":"dist/index.js"},"repository":{"type":"git","url":"git+https://github.com/rmferguson/shoal.git"},"homepage":"https://github.com/rmferguson/shoal#readme","bugs":{"url":"https://github.com/rmferguson/shoal/issues"},"author":{"name":"Robert Ferguson"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc && chmod +x dist/index.js","dev":"tsx src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit","test":"vitest run","prepublishOnly":"rm -rf dist && npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.10.2","zod":"^3.24.2"},"devDependencies":{"@types/node":"^22.15.3","tsx":"^4.19.3","typescript":"^5.8.3","vitest":"^4.1.5"},"keywords":["mcp","jira","atlassian","model-context-protocol"],"engines":{"node":">=22"},"license":"Apache-2.0","_id":"@aquarium-tools/shoal@1.1.0","gitHead":"0c68fb85371012d4e314b52e9120f66a2eeff0df","types":"./dist/index.d.ts","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-BRFdrxXAwT2RdSLER6VoZC8VcbMpEVVjk/liv1AZx5441K0eXKoMBFPG1m+Krzn9d65gnIwEkrOGtNSqAHy9XA==","shasum":"7c151b25f24e29a0cbab33492c38411f504c2ef8","tarball":"https://registry.npmjs.org/@aquarium-tools/shoal/-/shoal-1.1.0.tgz","fileCount":111,"unpackedSize":131799,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCGiyVzvxtxi3UMMT5dxtsdPhOCMRbwJtuTw7Wg+YJBygIhAPZIQZOjbVdzFtfU9ZR1KULhIKK+r0pfYqJBUPFbybtg"}]},"_npmUser":{"name":"rmferguson","email":"rmferguson@pm.me"},"directories":{},"maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/shoal_1.1.0_1786643288236_0.6557038685761845"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-02T06:06:06.898Z","modified":"2026-08-13T17:48:08.633Z","0.2.0":"2026-07-02T06:06:07.334Z","1.0.0":"2026-07-02T06:08:58.397Z","1.1.0":"2026-08-13T17:48:08.403Z"},"bugs":{"url":"https://github.com/rmferguson/shoal/issues"},"author":{"name":"Robert Ferguson"},"license":"Apache-2.0","homepage":"https://github.com/rmferguson/shoal#readme","keywords":["mcp","jira","atlassian","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/rmferguson/shoal.git"},"description":"Jira MCP server — correct, complete, open source","maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"readme":"# Shoal — Jira MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@aquarium-tools/shoal.svg)](https://www.npmjs.com/package/@aquarium-tools/shoal)\n[![CI](https://github.com/rmferguson/shoal/actions/workflows/ci.yml/badge.svg)](https://github.com/rmferguson/shoal/actions/workflows/ci.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nA local MCP server for Jira that works correctly. Built as a quality alternative to Atlassian's official server, which has unfixed bugs in issue creation, pagination, custom fields, and comment handling.\n\n## What's fixed\n\n| Atlassian bug | Shoal |\n|---------------|-------|\n| `createJiraIssue` creates two identical tickets on every call | Single POST, no duplicates |\n| Custom fields (story points, etc.) silently absent from responses | Full field passthrough |\n| JQL pagination never returns a next page cursor | Cursor-based pagination via `nextPageToken` |\n| `getJiraIssue` hangs indefinitely on media-heavy issues | 10s timeout + `rawAdf` fallback |\n| `transitionJiraIssue` fails when reopening issues (Resolution not cleared) | `clearResolution` flag |\n| Components rejected on issue create | Correct object serialization |\n| `@mentions` stripped from comments | ADF mention nodes |\n| No `getJiraIssueComments` tool | Included |\n| No `editJiraIssueComment` tool | Included |\n| No `manageJiraIssueLabels` tool | Included |\n| No issue link tools | `createJiraIssueLink` + `getJiraIssueLinkTypes` |\n| Epic operations require knowing Jira's internal field model (`customfield_10011`, `customfield_10014`) | `createJiraEpic` + `assignIssueToEpic` |\n\n## Tools\n\n### Jira\n\n`getJiraIssue`, `searchJiraIssuesUsingJql`, `getJiraIssueTypes`, `createJiraIssue`, `updateJiraIssue`, `getJiraTransitions`, `transitionJiraIssue`, `addCommentToJiraIssue`, `getJiraIssueComments`, `editJiraIssueComment`, `manageJiraIssueLabels`, `addAttachmentToJiraIssue`, `getJiraIssueLinkTypes`, `createJiraIssueLink`, `getJiraProjects`, `createJiraEpic`, `assignIssueToEpic`.\n\nFull parameter reference: [docs/tools.md](docs/tools.md)\n\n---\n\n## Documentation\n\n- [docs/tools.md](docs/tools.md) — full tool reference with all parameters and return values\n- [docs/jira-epics.md](docs/jira-epics.md) — epic model: classic vs next-gen projects, field differences\n- [docs/jira-fields.md](docs/jira-fields.md) — common custom fields, ADF format, account IDs\n- [docs/jira-api.md](docs/jira-api.md) — Jira API quirks, search endpoint changes, pagination, gotchas\n\n---\n\n## Requirements\n\n- Node.js 22+\n- An Atlassian API token — generate one at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)\n\n## Setup\n\n#### Claude Code\n\nAdd to your MCP config (`.claude/mcp.json` or via `claude mcp add`):\n\n```json\n{\n  \"mcpServers\": {\n    \"shoal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aquarium-tools/shoal\"],\n      \"env\": {\n        \"JIRA_SITE_URL\": \"https://yourorg.atlassian.net\",\n        \"ATLASSIAN_USER_EMAIL\": \"you@example.com\",\n        \"ATLASSIAN_API_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\n#### Other MCP clients\n\nUse the same config format with the appropriate client's MCP server section.\n\n#### Environment variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `JIRA_SITE_URL` | Yes | Your Jira instance URL, e.g. `https://yourorg.atlassian.net` |\n| `ATLASSIAN_USER_EMAIL` | Yes | Email address for your Atlassian account |\n| `ATLASSIAN_API_TOKEN` | Yes | API token from id.atlassian.com |\n\n## Running from source\n\n```bash\nnpm install\nnpm run dev        # run directly from source with tsx\nnpm run build      # compile to dist/\nnpm start          # run compiled server\nnpm test           # run test suite\nnpm run typecheck  # type-check without building\n```\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}