{"_id":"azure-devops-attachment-mcp-server","_rev":"3-b19e8fe38422b88e2e4540b5375d19eb","name":"azure-devops-attachment-mcp-server","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"azure-devops-attachment-mcp-server","version":"0.1.0","keywords":["mcp","model-context-protocol","mcp-server","azure-devops","azure-devops-server","tfs","work-items","attachments"],"author":{"name":"Mustafa Arslan"},"license":"MIT","_id":"azure-devops-attachment-mcp-server@0.1.0","maintainers":[{"name":"arslanmusta","email":"mustafa.arslan1992@gmail.com"}],"homepage":"https://github.com/arslanmusta/azure-devops-attachment-mcp-server#readme","bugs":{"url":"https://github.com/arslanmusta/azure-devops-attachment-mcp-server/issues"},"bin":{"azure-devops-attachment-mcp-server":"dist/index.js"},"dist":{"shasum":"a0d850279f795d70cf52a4d1e0b40bb9bd6e6666","tarball":"https://registry.npmjs.org/azure-devops-attachment-mcp-server/-/azure-devops-attachment-mcp-server-0.1.0.tgz","fileCount":23,"integrity":"sha512-lWpabglU6xvRthQ37DYlac0TW7bDUh32RLi9V/Bw3uyafmHhMbIIrNCbUE5EyuVWzLdnhErjlxltFSPys3zt7A==","signatures":[{"sig":"MEQCIGy6fS09j+rg5I3KRn+4T3ZZgsw77DmIv8PjcZxhe0cJAiBwJbQ4vbZdyuEST5AzjdXRYSpoCG8UXZdRNjlSHDiPsQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81343},"type":"module","engines":{"node":">=20"},"gitHead":"b6c3459cc2f5997529b8481f48c4f1b6a74c48dd","scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc -p tsconfig.json","test:watch":"vitest","prepublishOnly":"npm run typecheck && npm test && npm run build"},"_npmUser":{"name":"arslanmusta","email":"mustafa.arslan1992@gmail.com"},"repository":{"url":"git+https://github.com/arslanmusta/azure-devops-attachment-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server (stdio) for listing, adding, deleting and downloading work item attachments on on-premise Azure DevOps Server via the REST API","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^4.6.5","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.0","typescript":"^5.9.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/azure-devops-attachment-mcp-server_0.1.0_1789388865132_0.3714902276241365","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"azure-devops-attachment-mcp-server","version":"0.1.1","keywords":["mcp","model-context-protocol","mcp-server","azure-devops","azure-devops-server","tfs","work-items","attachments"],"author":{"name":"Mustafa Arslan"},"license":"MIT","_id":"azure-devops-attachment-mcp-server@0.1.1","maintainers":[{"name":"arslanmusta","email":"mustafa.arslan1992@gmail.com"}],"homepage":"https://github.com/arslanmusta/azure-devops-attachment-mcp-server#readme","bugs":{"url":"https://github.com/arslanmusta/azure-devops-attachment-mcp-server/issues"},"bin":{"azure-devops-attachment-mcp-server":"dist/index.js"},"dist":{"shasum":"b79ac2d573e85ee3dce25dff816da3b16384b1e3","tarball":"https://registry.npmjs.org/azure-devops-attachment-mcp-server/-/azure-devops-attachment-mcp-server-0.1.1.tgz","fileCount":23,"integrity":"sha512-Y64G5/vXY8fpeF8v5a6r4mYIffc86BkncnG/MCEITRK+btW7t5w88iF8BzXbV7ybfa7DAEI7PgrR5X9JfHsn6g==","signatures":[{"sig":"MEQCIGUSLdj1LTZebmWysagtdtMGa8rjn+AUI63lsUq0XFPeAiAIZnOwn2Om240OqY6QPjsLrZGmFqrzGVESpgz5vE84nw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIEiwvPRGsIquZPnM98yOAnYM4l1MHD3RRRMP9MJAt7qkAiEAnr8RUB3ydH4SPHvJBxwyR8IgveYnn2/DBehXxAlZUvs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/azure-devops-attachment-mcp-server@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":81518},"type":"module","engines":{"node":">=20"},"gitHead":"d3a807a0ab108bfe532127350cca4d4efff724bc","scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc -p tsconfig.json","test:watch":"vitest","prepublishOnly":"npm run typecheck && npm test && npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"2fb845cd-1c89-4f42-96aa-5940658db024"}},"repository":{"url":"git+https://github.com/arslanmusta/azure-devops-attachment-mcp-server.git","type":"git"},"_npmVersion":"12.2.0","description":"MCP server (stdio) for listing, adding, deleting and downloading work item attachments on on-premise Azure DevOps Server via the REST API","directories":{},"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.6.5","@modelcontextprotocol/sdk":"^1.32.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.0","typescript":"^5.9.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/azure-devops-attachment-mcp-server_0.1.1_1792413819684_0.2254492770667187","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"_id":"azure-devops-attachment-mcp-server@0.1.2","bin":{"azure-devops-attachment-mcp-server":"dist/index.js"},"bugs":{"url":"https://github.com/arslanmusta/azure-devops-attachment-mcp-server/issues"},"dist":{"shasum":"94f97b1fa70af9af15b5b50a836bac75ddc00de0","tarball":"https://registry.npmjs.org/azure-devops-attachment-mcp-server/-/azure-devops-attachment-mcp-server-0.1.2.tgz","fileCount":23,"integrity":"sha512-lIOdqAT75byJPaMNQNolUHZ0js1KLWyjh7DJQpQgjwpTb+SiYLq6euyECdkTEeL35N1N86VqMK1cvzyZwVderg==","signatures":[{"sig":"MEQCIGeyCb07DOFGbLz88VqXLW+7SSJAZRun0lMId1LSuJD1AiACErXXJoJXWQ1VXKhmjGCX2t3XxIVvwnDLJYWmlx+RvA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDY9JYyZAWyrm+Lkjb0DX1X/HMELq03RH7A/kQqFDY2fgIhANCYqLqbw9rm/GLsTQBkT6ilVR7pBZs3LgkgbwBZqSnG"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/azure-devops-attachment-mcp-server@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":81518},"name":"azure-devops-attachment-mcp-server","type":"module","author":{"name":"Mustafa Arslan"},"engines":{"node":">=20"},"gitHead":"b997680074021fdfeaeaaab7a483da6cf45e6b24","license":"MIT","scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc -p tsconfig.json","test:watch":"vitest","prepublishOnly":"npm run typecheck && npm test && npm run build"},"version":"0.1.2","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"2fb845cd-1c89-4f42-96aa-5940658db024"}},"homepage":"https://github.com/arslanmusta/azure-devops-attachment-mcp-server#readme","keywords":["mcp","model-context-protocol","mcp-server","azure-devops","azure-devops-server","tfs","work-items","attachments"],"repository":{"url":"git+https://github.com/arslanmusta/azure-devops-attachment-mcp-server.git","type":"git"},"_npmVersion":"12.2.1","description":"MCP server (stdio) for listing, adding, deleting and downloading work item attachments on on-premise Azure DevOps Server via the REST API","directories":{},"maintainers":[{"name":"arslanmusta","email":"mustafa.arslan1992@gmail.com"}],"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.6.7","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.0","typescript":"^5.9.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/azure-devops-attachment-mcp-server_0.1.2_1793017773815_0.21734439784625614"}}},"time":{"created":"2026-09-14T12:27:44.901Z","modified":"2026-10-26T12:29:35.792Z","0.1.0":"2026-09-14T12:27:45.270Z","0.1.1":"2026-10-19T12:43:39.765Z","0.1.2":"2026-10-26T12:29:33.924Z"},"bugs":{"url":"https://github.com/arslanmusta/azure-devops-attachment-mcp-server/issues"},"author":{"name":"Mustafa Arslan"},"license":"MIT","homepage":"https://github.com/arslanmusta/azure-devops-attachment-mcp-server#readme","keywords":["mcp","model-context-protocol","mcp-server","azure-devops","azure-devops-server","tfs","work-items","attachments"],"repository":{"url":"git+https://github.com/arslanmusta/azure-devops-attachment-mcp-server.git","type":"git"},"description":"MCP server (stdio) for listing, adding, deleting and downloading work item attachments on on-premise Azure DevOps Server via the REST API","maintainers":[{"name":"arslanmusta","email":"mustafa.arslan1992@gmail.com"}],"readme":"# azure-devops-attachment-mcp-server\n\n[![CI](https://github.com/arslanmusta/azure-devops-attachment-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/arslanmusta/azure-devops-attachment-mcp-server/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/azure-devops-attachment-mcp-server)](https://www.npmjs.com/package/azure-devops-attachment-mcp-server)\n[![M8ven Score](https://m8ven.ai/badge/mcp/arslanmusta-azure-devops-attachment-mcp-server-1da935)](https://m8ven.ai/mcp/arslanmusta-azure-devops-attachment-mcp-server-1da935)\n\nAn [MCP](https://modelcontextprotocol.io) server (stdio) that lets AI assistants manage **work item\nattachments** on **on-premise Azure DevOps Server** (2019 / 2020 / 2022, formerly TFS) through the REST\nAPI, authenticated with a Personal Access Token.\n\nIt exposes four tools:\n\n| Tool | What it does |\n| --- | --- |\n| `list_attachments` | Lists the attachments of a work item (name, size, comment, date, id, URL). |\n| `add_attachment` | Uploads a local file and attaches it to a work item. |\n| `delete_attachment` | Removes an attachment from a work item by id or unique file name. |\n| `download_attachment` | Saves an attachment to a local directory and returns the path. |\n\nNo extra dependencies beyond the MCP SDK and zod: it uses Node's built-in `fetch`, so `npx` starts fast.\n\n## Requirements\n\n- Node.js 20 or newer.\n- A Personal Access Token (PAT) for the collection with the **Work Items (Read & Write)** scope.\n- Network access from the machine running the MCP server to the Azure DevOps Server.\n\n## Quick start\n\nAdd the server to your MCP client configuration. The generic JSON form (Claude Desktop, Cursor, Windsurf,\nVS Code `mcp.json` and most other clients accept it):\n\n```json\n{\n  \"mcpServers\": {\n    \"azure-devops-attachments\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"azure-devops-attachment-mcp-server\"],\n      \"env\": {\n        \"AZURE_DEVOPS_URL\": \"https://tfs.company.local/tfs/DefaultCollection\",\n        \"AZURE_DEVOPS_PAT\": \"<your personal access token>\",\n        \"AZURE_DEVOPS_PROJECT\": \"MyProject\"\n      }\n    }\n  }\n}\n```\n\nClaude Code:\n\n```bash\nclaude mcp add azure-devops-attachments \\\n  -e AZURE_DEVOPS_URL=https://tfs.company.local/tfs/DefaultCollection \\\n  -e AZURE_DEVOPS_PAT=<your personal access token> \\\n  -e AZURE_DEVOPS_PROJECT=MyProject \\\n  -- npx -y azure-devops-attachment-mcp-server\n```\n\nThen ask your assistant things like:\n\n- \"List the attachments on work item 4711.\"\n- \"Attach `./reports/perf.xlsx` to bug 4711 with the comment 'perf run 2026-09'.\"\n- \"Download the attachment `spec.pdf` from work item 4711 into `~/Downloads`.\"\n- \"Remove the attachment `old-log.txt` from work item 4711.\"\n\n## Configuration\n\nAll configuration is passed through environment variables.\n\n| Variable | Required | Default | Description |\n| --- | --- | --- | --- |\n| `AZURE_DEVOPS_URL` | yes | | **Collection URL**, e.g. `https://tfs.company.local/tfs/DefaultCollection`. Include the `/tfs/<Collection>` path used by your server. |\n| `AZURE_DEVOPS_PAT` | yes | | Personal Access Token. Sent only as a Basic auth header to `AZURE_DEVOPS_URL`; never logged. |\n| `AZURE_DEVOPS_PROJECT` | no | | Default team project for the attachment endpoints. The work item's own project takes precedence when known. |\n| `AZURE_DEVOPS_API_VERSION` | no | `7.0` | REST `api-version`. `7.0` = Azure DevOps Server 2022, `6.0` = 2020, `5.0` = 2019. |\n| `AZURE_DEVOPS_DOWNLOAD_DIR` | no | process cwd | Directory where `download_attachment` saves files when no `outputDir` is given. |\n| `AZURE_DEVOPS_ALLOW_INSECURE_TLS` | no | `false` | Set to `true` to accept self-signed certificates. Insecure; prefer `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`. |\n\nThe server exits with code 1 and a message naming the missing variable when the configuration is incomplete.\n\n## Tools\n\nEvery tool returns a short human-readable summary plus `structuredContent` matching the documented shape.\nErrors come back as tool errors (`isError: true`) with an actionable message, for example which environment\nvariable to check after an HTTP 401.\n\n### `list_attachments`\n\n| Input | Type | Notes |\n| --- | --- | --- |\n| `workItemId` | integer | Required. |\n\nReturns `{ workItemId, workItemRev, count, attachments[] }` where each attachment has\n`{ id, name, size, comment, createdDate, url, relationIndex }`. `size` is `null` when the server does not\nreport it (older servers or migrated data).\n\n### `add_attachment`\n\n| Input | Type | Notes |\n| --- | --- | --- |\n| `workItemId` | integer | Required. |\n| `filePath` | string | Required. Absolute or cwd-relative path of a local file (max 130 MB). |\n| `fileName` | string | Optional. Name stored on the server; defaults to the file's base name. |\n| `comment` | string | Optional. Comment shown next to the attachment. |\n| `project` | string | Optional. Team project for the upload; defaults to the work item's project, then `AZURE_DEVOPS_PROJECT`. |\n\nReturns `{ workItemId, workItemRev, attachment: { id, name, size, url, comment } }`.\n\n### `delete_attachment`\n\n| Input | Type | Notes |\n| --- | --- | --- |\n| `workItemId` | integer | Required. |\n| `attachmentId` | GUID | One of `attachmentId` / `name` is required. |\n| `name` | string | Exact file name; rejected with the candidate ids when several attachments share it. |\n\nReturns `{ workItemId, workItemRev, removed: { id, name, relationIndex }, note }`. Only the link between the\nwork item and the file is removed; Azure DevOps has no REST endpoint that deletes the stored file itself\n(this is also what the web UI does).\n\n### `download_attachment`\n\n| Input | Type | Notes |\n| --- | --- | --- |\n| `workItemId` | integer | Required. |\n| `attachmentId` | GUID | One of `attachmentId` / `name` is required. |\n| `name` | string | Exact file name; must be unique on the work item. |\n| `fileName` | string | Optional. Local file name; defaults to the server-side name (sanitized). |\n| `outputDir` | string | Optional. Defaults to `AZURE_DEVOPS_DOWNLOAD_DIR`, then the server's cwd. |\n| `project` | string | Optional. Team project for the download URL. |\n\nReturns `{ id, name, path, size, workItemId }` with the absolute path of the saved file. Existing files are\nnever overwritten: a ` (1)`, ` (2)`, ... suffix is added instead.\n\n## How it maps to the REST API\n\n| Tool | Calls |\n| --- | --- |\n| list | `GET {collection}/_apis/wit/workitems/{id}?$expand=relations` and filters `rel == \"AttachedFile\"`. |\n| add | `POST {collection}/{project}/_apis/wit/attachments?fileName=...` (octet-stream), then `PATCH .../workitems/{id}` adding an `AttachedFile` relation, guarded by `test /rev`. |\n| delete | `PATCH .../workitems/{id}` removing `/relations/{index}`, guarded by `test /rev`. |\n| download | `GET {collection}/{project}/_apis/wit/attachments/{guid}?fileName=...&download=true`, streamed to disk. |\n\nDetails that matter on-premise:\n\n- Work items are addressed at collection level, so a work item in any project of the collection works.\n- Download URLs are rebuilt from `AZURE_DEVOPS_URL` instead of trusting the host inside the relation URL,\n  which on some servers points at an internal name.\n- `X-TFS-FedAuthRedirect: Suppress` is sent so a rejected PAT yields a clear 401 instead of a sign-in page.\n- A failed `test /rev` (concurrent edit) triggers exactly one refetch-and-retry.\n\n## Limitations\n\n- Simple uploads only: files above 130 MB (chunked upload) are rejected with a clear message.\n- PAT authentication only; NTLM / Windows integrated authentication is not supported.\n- Deleting removes the attachment link; the blob stays on the server (no API exists to purge it).\n- stdio transport only.\n\n## Security notes\n\n- The PAT is used solely as a Basic auth header for requests to `AZURE_DEVOPS_URL` and never appears in\n  logs, tool output or error messages.\n- Everything the server logs goes to stderr; stdout is reserved for the MCP protocol.\n- Downloaded file names are sanitized (path separators, `..`, control characters) and files are written\n  only inside the requested output directory.\n- `AZURE_DEVOPS_ALLOW_INSECURE_TLS=true` disables certificate verification for the whole process. Use it only\n  on trusted networks; adding your CA via `NODE_EXTRA_CA_CERTS` is the safer option.\n\n## Troubleshooting\n\n| Symptom | Likely cause |\n| --- | --- |\n| `Authentication failed (HTTP 401)` | PAT invalid, expired, created in another collection, or missing the Work Items (Read & Write) scope. |\n| `returned a sign-in page instead of data` | Same as above, or `AZURE_DEVOPS_URL` is not the collection URL (missing `/tfs/DefaultCollection`). |\n| `Could not reach ...: SELF_SIGNED_CERT_IN_CHAIN` | Self-signed certificate: set `NODE_EXTRA_CA_CERTS` or, less safely, `AZURE_DEVOPS_ALLOW_INSECURE_TLS=true`. |\n| `Could not reach ...: ENOTFOUND` / `ECONNREFUSED` | Wrong host in `AZURE_DEVOPS_URL`, VPN not connected, or the server is down. |\n| `TF401232: Work item ... does not exist` | Wrong id, or the PAT owner cannot read that work item. |\n| `2 attachments named \"...\"` | Pass `attachmentId` (from `list_attachments`) instead of `name`. |\n\nRun `npx @modelcontextprotocol/inspector npx -y azure-devops-attachment-mcp-server` with the environment\nvariables set to try the tools interactively.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck   # tsc --noEmit over src and tests\nnpm test            # vitest (builds dist/ first so the bin tests use the real entry point)\nnpm run build       # emits dist/\nnpm run inspect     # MCP Inspector against dist/index.js\n```\n\nTests run against a fake `fetch`; no Azure DevOps Server is needed. See [docs/design.md](docs/design.md)\nfor the design notes.\n\n### Releasing\n\n1. Bump `version` in `package.json` and commit.\n2. Tag it: `git tag v<version> && git push --tags`.\n3. The `Publish to npm` workflow builds, tests and publishes with provenance. It needs an `NPM_TOKEN`\n   repository secret (an npm automation token).\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}