{"_id":"@braidhq/source-loader-mcp","_rev":"5-2f8375a35051cd62c5ef97af504a59e4","name":"@braidhq/source-loader-mcp","dist-tags":{"latest":"0.6.0"},"versions":{"0.4.0":{"name":"@braidhq/source-loader-mcp","version":"0.4.0","license":"MIT","_id":"@braidhq/source-loader-mcp@0.4.0","maintainers":[{"name":"mroops0111","email":"mroops0111@gmail.com"}],"homepage":"https://github.com/mroops0111/braid#readme","bugs":{"url":"https://github.com/mroops0111/braid/issues"},"dist":{"shasum":"4dca76430b31408f5cefbfb3a499c2f4523b7932","tarball":"https://registry.npmjs.org/@braidhq/source-loader-mcp/-/source-loader-mcp-0.4.0.tgz","fileCount":28,"integrity":"sha512-0zikrmg9mnyd3JC0tE+qltTQmXMRkvcmtcrWS1kbYzJmFQ+A8mYTQ3eCY3TCOSmSfG0VNqJ3HTjtyz5DGIi3HQ==","signatures":[{"sig":"MEYCIQCxiwiExb5yD48WE2jNhZKAj7fULQstQPya6Rg22ZB/mAIhALFrsrdP9FDrk4tjJl4vAZybVMJ80q0qqmTAZ+anSBDB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":142707},"main":"./dist/index.js","type":"module","_from":"file:packages/source-loader-mcp/braidhq-source-loader-mcp-0.4.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"test":"vitest run --coverage","build":"tsc -p tsconfig.json","clean":"rm -rf dist .turbo *.tsbuildinfo coverage","typecheck":"tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"},"_npmUser":{"name":"mroops0111","email":"mroops0111@gmail.com"},"_resolved":"/Users/KdanMobile/mroops/side-projects/braid/packages/source-loader-mcp/braidhq-source-loader-mcp-0.4.0.tgz","_integrity":"sha512-0zikrmg9mnyd3JC0tE+qltTQmXMRkvcmtcrWS1kbYzJmFQ+A8mYTQ3eCY3TCOSmSfG0VNqJ3HTjtyz5DGIi3HQ==","repository":{"url":"git+https://github.com/mroops0111/braid.git","type":"git","directory":"packages/source-loader-mcp"},"_npmVersion":"10.9.4","description":"MCP source-loader plugin for Braid. Mirror an API-backed source into markdown through an MCP tool.","directories":{},"_nodeVersion":"22.21.1","dependencies":{"zod":"^4.2.1","yaml":"^2.9.0","@braidhq/sdk":"0.4.0","@braidhq/core":"0.4.0","@braidhq/schema":"0.4.0","@modelcontextprotocol/client":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^6.0.3","@hono/node-server":"^1.19.6","@braidhq/test-utils":"0.4.0","@modelcontextprotocol/server":"^2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/source-loader-mcp_0.4.0_1787452750250_0.4326817826841267","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@braidhq/source-loader-mcp","version":"0.4.1","license":"MIT","_id":"@braidhq/source-loader-mcp@0.4.1","maintainers":[{"name":"mroops0111","email":"mroops0111@gmail.com"}],"homepage":"https://github.com/mroops0111/braid#readme","bugs":{"url":"https://github.com/mroops0111/braid/issues"},"dist":{"shasum":"2d2bdc6eb38b8fef7b6c1a6e9d3f535e46bdfc61","tarball":"https://registry.npmjs.org/@braidhq/source-loader-mcp/-/source-loader-mcp-0.4.1.tgz","fileCount":27,"integrity":"sha512-vS6yzJ3/QTMWhBopLXSnpDE3ne+V7ShBcAeBlMTvfNGxjVfvYtIno6yDjI4rE6yBoZWiR7wWwXBLI55tOj5xaw==","signatures":[{"sig":"MEUCIAjTtWkPO+waelvFMOJ+w6LXBHE3+rS0z0XUU8CFdxfDAiEA06d2RoFniUDlsYYxdwG4McSTQ7IvtBKuRf/cbiUl8e4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@braidhq%2fsource-loader-mcp@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":46607},"main":"./dist/index.js","type":"module","_from":"file:.release/braidhq-source-loader-mcp-0.4.1.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"test":"vitest run --coverage","build":"tsc -p tsconfig.json","clean":"rm -rf dist .turbo *.tsbuildinfo coverage","typecheck":"tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:824c5400-4009-4ef8-b2d5-0cccc351d8b8"}},"_resolved":"/home/runner/work/braid/braid/.release/braidhq-source-loader-mcp-0.4.1.tgz","_integrity":"sha512-vS6yzJ3/QTMWhBopLXSnpDE3ne+V7ShBcAeBlMTvfNGxjVfvYtIno6yDjI4rE6yBoZWiR7wWwXBLI55tOj5xaw==","repository":{"url":"git+https://github.com/mroops0111/braid.git","type":"git","directory":"packages/source-loader-mcp"},"_npmVersion":"12.0.2","description":"MCP source-loader plugin for Braid. Mirror an API-backed source into markdown through an MCP tool.","directories":{},"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.2.1","yaml":"^2.9.0","@braidhq/sdk":"0.4.1","@braidhq/core":"0.4.1","@braidhq/schema":"0.4.1","@modelcontextprotocol/client":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^6.0.3","@hono/node-server":"^1.19.6","@braidhq/test-utils":"0.4.1","@modelcontextprotocol/server":"^2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/source-loader-mcp_0.4.1_1788142187031_0.5630216158468775","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@braidhq/source-loader-mcp","version":"0.4.2","license":"MIT","_id":"@braidhq/source-loader-mcp@0.4.2","maintainers":[{"name":"mroops0111","email":"mroops0111@gmail.com"}],"homepage":"https://github.com/mroops0111/braid#readme","bugs":{"url":"https://github.com/mroops0111/braid/issues"},"dist":{"shasum":"00c5618275784e55c4d914542ca2d2bb29e945e3","tarball":"https://registry.npmjs.org/@braidhq/source-loader-mcp/-/source-loader-mcp-0.4.2.tgz","fileCount":27,"integrity":"sha512-8XVZIc+PrBxatjNiH9NlR4SrMY97Khj8d2ttPBknRr4altv1D9uvgP7qqQ01KzAKDqWtQ9QkRugXEk+bOfwZvg==","signatures":[{"sig":"MEYCIQCcBlrjZbSQ+9MVy4hkBUP96AvT0vggmqv9/XLspGatjwIhAOSZpeFpi5RFdd935BfM3k4XUdGbpYGVM1S8APXbVWV4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@braidhq%2fsource-loader-mcp@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":46607},"main":"./dist/index.js","type":"module","_from":"file:.release/braidhq-source-loader-mcp-0.4.2.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"test":"vitest run --coverage","build":"tsc -p tsconfig.json","clean":"rm -rf dist .turbo *.tsbuildinfo coverage","typecheck":"tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:824c5400-4009-4ef8-b2d5-0cccc351d8b8"}},"_resolved":"/home/runner/work/braid/braid/.release/braidhq-source-loader-mcp-0.4.2.tgz","_integrity":"sha512-8XVZIc+PrBxatjNiH9NlR4SrMY97Khj8d2ttPBknRr4altv1D9uvgP7qqQ01KzAKDqWtQ9QkRugXEk+bOfwZvg==","repository":{"url":"git+https://github.com/mroops0111/braid.git","type":"git","directory":"packages/source-loader-mcp"},"_npmVersion":"12.0.2","description":"MCP source-loader plugin for Braid. Mirror an API-backed source into markdown through an MCP tool.","directories":{},"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.2.1","yaml":"^2.9.0","@braidhq/sdk":"0.4.2","@braidhq/core":"0.4.2","@braidhq/schema":"0.4.2","@modelcontextprotocol/client":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^6.0.3","@hono/node-server":"^1.19.6","@braidhq/test-utils":"0.4.2","@modelcontextprotocol/server":"^2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/source-loader-mcp_0.4.2_1788169244698_0.6645762254890542","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@braidhq/source-loader-mcp","version":"0.5.0","license":"MIT","_id":"@braidhq/source-loader-mcp@0.5.0","maintainers":[{"name":"mroops0111","email":"mroops0111@gmail.com"}],"homepage":"https://github.com/mroops0111/braid#readme","bugs":{"url":"https://github.com/mroops0111/braid/issues"},"dist":{"shasum":"61d6ff7b68ae376cf3838f0787afe60b014f8d85","tarball":"https://registry.npmjs.org/@braidhq/source-loader-mcp/-/source-loader-mcp-0.5.0.tgz","fileCount":27,"integrity":"sha512-J8P2BgvJ9Pa8wZxjW+ksqlXz/Qh88tkyTtQecj/EM8LA3YAQZtJDYPlaCbpv5RsndlIl6q/R1kNjsHgccH99Qw==","signatures":[{"sig":"MEUCIQDAaDp0vkSUIcbDRjR8thrJ4yy303pQM4ubDG2iwqetJAIgHg5in0vW+lvItSs2p098oUMgNfoSxbdi1QrB5xnjX2E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@braidhq%2fsource-loader-mcp@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":46607},"main":"./dist/index.js","type":"module","_from":"file:.release/braidhq-source-loader-mcp-0.5.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"test":"vitest run --coverage","build":"tsc -p tsconfig.json","clean":"rm -rf dist .turbo *.tsbuildinfo coverage","typecheck":"tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:824c5400-4009-4ef8-b2d5-0cccc351d8b8"}},"_resolved":"/home/runner/work/braid/braid/.release/braidhq-source-loader-mcp-0.5.0.tgz","_integrity":"sha512-J8P2BgvJ9Pa8wZxjW+ksqlXz/Qh88tkyTtQecj/EM8LA3YAQZtJDYPlaCbpv5RsndlIl6q/R1kNjsHgccH99Qw==","repository":{"url":"git+https://github.com/mroops0111/braid.git","type":"git","directory":"packages/source-loader-mcp"},"_npmVersion":"12.0.2","description":"MCP source-loader plugin for Braid. Mirror an API-backed source into markdown through an MCP tool.","directories":{},"_nodeVersion":"24.20.0","dependencies":{"zod":"^4.2.1","yaml":"^2.9.0","@braidhq/sdk":"0.5.0","@braidhq/core":"0.5.0","@braidhq/schema":"0.5.0","@modelcontextprotocol/client":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^6.0.3","@hono/node-server":"^1.19.6","@braidhq/test-utils":"0.5.0","@modelcontextprotocol/server":"^2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/source-loader-mcp_0.5.0_1788515103139_0.984169003326451","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"_id":"@braidhq/source-loader-mcp@0.6.0","bugs":{"url":"https://github.com/mroops0111/braid/issues"},"dist":{"shasum":"5ebe1e9076bf3f2807abe2eeea4bff80fd60f1c1","tarball":"https://registry.npmjs.org/@braidhq/source-loader-mcp/-/source-loader-mcp-0.6.0.tgz","fileCount":27,"integrity":"sha512-NyW3viENv1Fcu39UCzIg5lvu+iuaK5KA//1oPJQddxkGL7UoVrgp5151LNMsnislFrGwnB7N4e6EFXd4ckGWyg==","signatures":[{"sig":"MEQCIEAIFuGwrmMTFJ8p0FgG8iIIwJ1tCrlWJ367G7KoC4pKAiBPkPtKYsxG6+6X3FgGvKqBJ8e6fNt8Q6Z0s5Z5SmiQXQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDi+xl9+xH6k0fCXkf4NCVHeGI8dpolejWV1Hudl4gUtgIhAOpVGaZOk+cQWH7AKoOG+c0ruZAF/mjPCe0c/k9gcEr6"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@braidhq%2fsource-loader-mcp@0.6.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":46607},"main":"./dist/index.js","name":"@braidhq/source-loader-mcp","type":"module","_from":"file:.release/braidhq-source-loader-mcp-0.6.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"license":"MIT","scripts":{"test":"vitest run --coverage","build":"tsc -p tsconfig.json","clean":"rm -rf dist .turbo *.tsbuildinfo coverage","typecheck":"tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"},"version":"0.6.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:824c5400-4009-4ef8-b2d5-0cccc351d8b8"}},"homepage":"https://github.com/mroops0111/braid#readme","_resolved":"/home/runner/work/braid/braid/.release/braidhq-source-loader-mcp-0.6.0.tgz","_integrity":"sha512-NyW3viENv1Fcu39UCzIg5lvu+iuaK5KA//1oPJQddxkGL7UoVrgp5151LNMsnislFrGwnB7N4e6EFXd4ckGWyg==","repository":{"url":"git+https://github.com/mroops0111/braid.git","type":"git","directory":"packages/source-loader-mcp"},"_npmVersion":"12.0.2","description":"MCP source-loader plugin for Braid. Mirror an API-backed source into markdown through an MCP tool.","directories":{},"maintainers":[{"name":"mroops0111","email":"mroops0111@gmail.com"}],"_nodeVersion":"24.20.0","dependencies":{"zod":"^4.2.1","yaml":"^2.9.0","@braidhq/sdk":"0.6.0","@braidhq/core":"0.6.0","@braidhq/schema":"0.6.0","@modelcontextprotocol/client":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^6.0.3","@hono/node-server":"^1.19.6","@braidhq/test-utils":"0.6.0","@modelcontextprotocol/server":"^2.0.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/source-loader-mcp_0.6.0_1789090856176_0.8562655650850419"}}},"time":{"created":"2026-08-23T02:39:10.036Z","modified":"2026-09-11T01:40:56.643Z","0.4.0":"2026-08-23T02:39:10.392Z","0.4.1":"2026-08-31T02:09:47.163Z","0.4.2":"2026-08-31T09:40:44.857Z","0.5.0":"2026-09-04T09:45:03.287Z","0.6.0":"2026-09-11T01:40:56.274Z"},"bugs":{"url":"https://github.com/mroops0111/braid/issues"},"license":"MIT","homepage":"https://github.com/mroops0111/braid#readme","repository":{"url":"git+https://github.com/mroops0111/braid.git","type":"git","directory":"packages/source-loader-mcp"},"description":"MCP source-loader plugin for Braid. Mirror an API-backed source into markdown through an MCP tool.","maintainers":[{"name":"mroops0111","email":"mroops0111@gmail.com"}],"readme":"# @braidhq/source-loader-mcp\n\nMirrors an API-backed source into markdown by calling one MCP tool until its\npages run out. One file per item, which is what makes an issue tracker or a\nwiki a tracked source rather than a lookup an agent happens to make mid-run.\n\n## The Shape It Expects\n\nThe loader knows a tool name and where the parts of a reply live. Nothing else.\nBoth are configuration, and the defaults describe one envelope:\n\n```text\nthe tool takes\n  { \"since\": \"2026-01-01T00:00:00Z\", \"cursor\": \"abc\", \"limit\": 100 }\nand answers with\n  { \"items\": [{ \"id\": \"1\", \"title\": \"…\", \"body\": \"…\", \"updatedAt\": \"…\" }],\n    \"nextCursor\": \"def\" }\n```\n\nPoint this at a server shaped that way and the whole config is a URL:\n\n```yaml\nkind: filesystem\nid: issues\nrole: intent\npath: ./intents/issues\nloader:\n  kind: mcp\n  config:\n    url: https://gateway.internal/redmine/mcp\n    headers:\n      Authorization: Bearer ${REDMINE_TOKEN}\n```\n\nPoint it at a server you do not control and name its shape instead:\n\n```yaml\nconfig:\n  url: https://jira.internal/mcp\n  tool: search_issues\n  response:\n    items: data.records\n    cursor: data.next\n  item:\n    id: key\n    title: summary\n    body: description\n    updatedAt: touched\n```\n\nEach group carries one rule, which is why none of the keys need a suffix.\n`arguments` names arguments the tool takes, `response` names keys in the reply,\nand `item` names keys on one item. Every path may be dotted.\n\n`${VAR}` in `url` and in any header resolves against the server's environment,\nso a credential never lands in `PRODUCT.md`.\n\n## What Lands On Disk\n\nOne `<id>.md` per item. Frontmatter carries every scalar the item has, not only\nthe mapped ones, so a status or an assignee reaches the agent without being\nconfigured. The three mapped fields are also written under canonical names, so\na reader sees `title` whether the server called it `subject` or `summary`.\n\nAn item is written only when its rendering differs, so an untouched item stays\nbyte-identical across syncs and the fingerprints downstream do not churn.\n\n## Incremental Reads\n\nThe newest `updatedAt` seen becomes the next sync's floor, recorded in\n`.braid-mcp-cursor.json` beside the documents. The leading dot keeps it out of\nthe unit listing.\n\nThe mark is stored against the URL and tool it came from, so retargeting a\nsource re-reads it whole instead of silently skipping everything older.\n\nStarting from a date rather than the whole history is the tool's own business,\nthrough a default on its `since` argument. Nothing here needs to know.\n\n## Two Things To Know\n\n**Paging is walked here.** A gateway maps one tool call onto one upstream\nrequest and does not loop. The walk stops at `maxPages`, and reports\n`truncated`, so a server that always answers with a cursor cannot spin forever.\nA repeated cursor is treated as an error rather than a ceiling, since it means\npaging cannot advance at all.\n\n**A failed call arrives on its own channel.** MCP reports a tool failure as\n`isError` with a shape the server authors, never as the configured envelope. It\nis raised, because a sync that quietly mirrors nothing is worse than one that\nstops.\n\n## Transport\n\nStreamable HTTP only. The MCP server is a process the operator runs, so this\nspeaks to it and never manages its lifetime. Handling stdio would put spawning,\ntimeouts, and orphan reaping inside the Braid server for a case nobody has\nasked for yet.\n\n## A Note On The Name\n\n`loader.kind: mcp` is not the same as `kind: mcp`, the source kind in the\nschema. A source using this loader is a `filesystem` source, because what it\nproduces is a directory of files. Only the way that directory gets filled is\nMCP. The two never appear in the same position.\n","readmeFilename":"README.md"}