{"_id":"@bradford-tech/npm-package-readme-mcp-server","_rev":"4-b51c549b9c5743915c3c4fa6440dc365","name":"@bradford-tech/npm-package-readme-mcp-server","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.4":{"name":"@bradford-tech/npm-package-readme-mcp-server","version":"0.1.4","keywords":["mcp","npm","readme","package","documentation"],"author":{"name":"sbs44"},"license":"MIT","_id":"@bradford-tech/npm-package-readme-mcp-server@0.1.4","maintainers":[{"name":"sbs44","email":"focal-flusher.0g@icloud.com"}],"homepage":"https://github.com/bradford-tech/npm-package-readme-mcp-server#readme","bugs":{"url":"https://github.com/bradford-tech/npm-package-readme-mcp-server/issues"},"bin":{"npm-package-readme-mcp-server":"dist/index.js"},"dist":{"shasum":"10553af1aa1bc822fceb3bd2eb28336c465d7e62","tarball":"https://registry.npmjs.org/@bradford-tech/npm-package-readme-mcp-server/-/npm-package-readme-mcp-server-0.1.4.tgz","fileCount":56,"integrity":"sha512-/N+jehApP2XnvjfDJ2CA55jZF51dkAI9OIVxxkjmFVEjv/wUyKmex8hnZSnQaEy9+2HHvVPVKtNk18gDnK9eTw==","signatures":[{"sig":"MEUCIQDtvdQfFPmcjhGaAL04JOTlL4BQtHA6r5XQpBnc9manSQIgIkEoaBRXM8KzI99uSrDAVE/MauI/ssBhGRao/CtQ+o0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":157570},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"4c358d41d0a61d9bfd8a2cd3c35c8004c037d3ce","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"sbs44","email":"focal-flusher.0g@icloud.com"},"repository":{"url":"git+https://github.com/bradford-tech/npm-package-readme-mcp-server.git","type":"git"},"_npmVersion":"11.13.0","description":"MCP server for fetching npm package README and usage information","directories":{},"_nodeVersion":"24.16.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","eslint":"^8.0.0","vitest":"^4.1.8","typescript":"^5.0.0","@types/node":"^20.19.41","@typescript-eslint/parser":"^8.60.1","@typescript-eslint/eslint-plugin":"^8.60.1"},"_npmOperationalInternal":{"tmp":"tmp/npm-package-readme-mcp-server_0.1.4_1780862750739_0.2744651927769217","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@bradford-tech/npm-package-readme-mcp-server","version":"0.1.5","keywords":["mcp","npm","readme","package","documentation"],"author":{"name":"sbs44"},"license":"MIT","_id":"@bradford-tech/npm-package-readme-mcp-server@0.1.5","maintainers":[{"name":"sbs44","email":"focal-flusher.0g@icloud.com"}],"homepage":"https://github.com/bradford-tech/npm-package-readme-mcp-server#readme","bugs":{"url":"https://github.com/bradford-tech/npm-package-readme-mcp-server/issues"},"bin":{"npm-package-readme-mcp-server":"dist/index.js"},"dist":{"shasum":"e4ebac6f1ec81c10f59bedb55034a48e20af6707","tarball":"https://registry.npmjs.org/@bradford-tech/npm-package-readme-mcp-server/-/npm-package-readme-mcp-server-0.1.5.tgz","fileCount":56,"integrity":"sha512-+SnZMROADt6oi3Zv3UyXyzzJ77p1LQZo6zODcX2uhplP27CA7r7P86ZpMajR0oZYq58S1rptSsOKHwgd7OiS+Q==","signatures":[{"sig":"MEUCIBSZotxbdaM3M/HluTbUhfD9bozR6IPMQAmZJilVw80ZAiEA3rVblwDbABWQyVEFvhek5X3fgcLZ/+SSRF2JbsSSFXE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bradford-tech%2fnpm-package-readme-mcp-server@0.1.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":155387},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"c29abccef86aaa9ea1b45977236965951b43185b","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28678b70-5fda-404b-9635-62398841f573"}},"repository":{"url":"git+https://github.com/bradford-tech/npm-package-readme-mcp-server.git","type":"git"},"_npmVersion":"11.13.0","description":"MCP server for fetching npm package README and usage information","directories":{},"_nodeVersion":"24.16.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","eslint":"^8.0.0","vitest":"^4.1.8","typescript":"^5.0.0","@types/node":"^20.19.41","@typescript-eslint/parser":"^8.60.1","@typescript-eslint/eslint-plugin":"^8.60.1"},"_npmOperationalInternal":{"tmp":"tmp/npm-package-readme-mcp-server_0.1.5_1780863842169_0.3105703049835411","host":"s3://npm-registry-packages-npm-production"}},"0.1.6":{"name":"@bradford-tech/npm-package-readme-mcp-server","version":"0.1.6","keywords":["mcp","npm","readme","package","documentation"],"author":{"name":"sbs44"},"license":"MIT","_id":"@bradford-tech/npm-package-readme-mcp-server@0.1.6","maintainers":[{"name":"sbs44","email":"focal-flusher.0g@icloud.com"}],"homepage":"https://github.com/bradford-tech/npm-package-readme-mcp-server#readme","bugs":{"url":"https://github.com/bradford-tech/npm-package-readme-mcp-server/issues"},"bin":{"npm-package-readme-mcp-server":"dist/index.js"},"dist":{"shasum":"2e79f1f26b7c96bbaa2acab883c6fae83c78981e","tarball":"https://registry.npmjs.org/@bradford-tech/npm-package-readme-mcp-server/-/npm-package-readme-mcp-server-0.1.6.tgz","fileCount":56,"integrity":"sha512-yH68aW9zKIsGYP4oiRkHo7H8tmm+vIvR0si5xAcCMTaFQ5niFv+Gzx8YCkDzuhTxAQyeIzGIUmrpaAalWdcCvg==","signatures":[{"sig":"MEQCIFFI3Z/d3K8e7J4WBNgJVIX3Nyc30mIJMnm5q6P9pN+/AiAnRT9QHsuwtPeR6s5ftOtfpOWpHbHGNS6NhgkCsZglUA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bradford-tech%2fnpm-package-readme-mcp-server@0.1.6","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":157711},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.19.0"},"gitHead":"206c8acebc49d6f50719fda8e85f9ed55fcc3285","scripts":{"dev":"tsx src/index.ts","fix":"npm run format:write && npm run lint:fix","lint":"eslint . --quiet --max-warnings 0","test":"vitest run","build":"tsc","start":"node dist/index.js","format":"prettier . --log-level warn","lint:fix":"eslint . --fix --quiet --max-warnings 0","typecheck":"tsc --noEmit","format:write":"prettier . --write --log-level warn","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28678b70-5fda-404b-9635-62398841f573"}},"repository":{"url":"git+https://github.com/bradford-tech/npm-package-readme-mcp-server.git","type":"git"},"_npmVersion":"11.13.0","description":"MCP server for fetching npm package README and usage information","directories":{},"_nodeVersion":"24.16.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","jiti":"^2.7.0","eslint":"^10.4.1","vitest":"^4.1.8","globals":"^17.6.0","prettier":"^3.8.3","@eslint/js":"^10.0.1","typescript":"^5.0.0","@types/node":"^20.19.41","typescript-eslint":"^8.60.1","eslint-config-prettier":"^10.1.8","prettier-plugin-packagejson":"^3.0.2","eslint-config-flat-gitignore":"^2.3.0","prettier-plugin-organize-imports":"^4.3.0"},"_npmOperationalInternal":{"tmp":"tmp/npm-package-readme-mcp-server_0.1.6_1780961924388_0.3517888238140696","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@bradford-tech/npm-package-readme-mcp-server","version":"0.2.0","description":"MCP server for fetching npm package README and usage information","keywords":["mcp","npm","readme","package","documentation"],"homepage":"https://github.com/bradford-tech/npm-package-readme-mcp-server#readme","bugs":{"url":"https://github.com/bradford-tech/npm-package-readme-mcp-server/issues"},"repository":{"type":"git","url":"git+https://github.com/bradford-tech/npm-package-readme-mcp-server.git"},"license":"MIT","author":{"name":"sbs44"},"type":"module","main":"dist/index.js","bin":{"npm-package-readme-mcp-server":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","fix":"npm run format:write && npm run lint:fix","format":"prettier . --log-level warn","format:write":"prettier . --write --log-level warn","lint":"eslint . --quiet --max-warnings 0","lint:fix":"eslint . --fix --quiet --max-warnings 0","prepublishOnly":"npm run build","start":"node dist/index.js","test":"vitest run","typecheck":"tsc --noEmit"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^4.4.3"},"devDependencies":{"@eslint/js":"^10.0.1","@types/node":"^20.19.41","eslint":"^10.4.1","eslint-config-flat-gitignore":"^2.3.0","eslint-config-prettier":"^10.1.8","globals":"^17.6.0","jiti":"^2.7.0","prettier":"^3.8.3","prettier-plugin-organize-imports":"^4.3.0","prettier-plugin-packagejson":"^3.0.2","tsx":"^4.0.0","typescript":"^5.0.0","typescript-eslint":"^8.60.1","vitest":"^4.1.8"},"engines":{"node":">=20.0.0"},"publishConfig":{"access":"public"},"gitHead":"923c95f32fe265220a42190aef4feae0a262149a","types":"./dist/index.d.ts","_id":"@bradford-tech/npm-package-readme-mcp-server@0.2.0","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-cx8N/LViM0hvAkt3cCw5yHmtIt77nJkxgOCF1DDmj65VUPv4bYzERghB30fw6yNJ3U4hDeHmBkNDT9EfXqA0mw==","shasum":"b62bac10c787dea3c189f67ab438e94ff575ea7c","tarball":"https://registry.npmjs.org/@bradford-tech/npm-package-readme-mcp-server/-/npm-package-readme-mcp-server-0.2.0.tgz","fileCount":55,"unpackedSize":143542,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bradford-tech%2fnpm-package-readme-mcp-server@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDjqOkwBbpdarwGO7zq825P5tvl9QBX8ARgZSL9MN1wxgIgO2Lnw+LPbhR1ZhLZZJtckyV4F0iamLzyQxzN7yGWa+4="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:28678b70-5fda-404b-9635-62398841f573"}},"directories":{},"maintainers":[{"name":"sbs44","email":"focal-flusher.0g@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/npm-package-readme-mcp-server_0.2.0_1780964126287_0.6322564717686459"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-07T20:05:50.541Z","modified":"2026-06-09T00:15:26.719Z","0.1.4":"2026-06-07T20:05:50.972Z","0.1.5":"2026-06-07T20:24:02.304Z","0.1.6":"2026-06-08T23:38:44.523Z","0.2.0":"2026-06-09T00:15:26.425Z"},"bugs":{"url":"https://github.com/bradford-tech/npm-package-readme-mcp-server/issues"},"author":{"name":"sbs44"},"license":"MIT","homepage":"https://github.com/bradford-tech/npm-package-readme-mcp-server#readme","keywords":["mcp","npm","readme","package","documentation"],"repository":{"type":"git","url":"git+https://github.com/bradford-tech/npm-package-readme-mcp-server.git"},"description":"MCP server for fetching npm package README and usage information","maintainers":[{"name":"sbs44","email":"focal-flusher.0g@icloud.com"}],"readme":"# @bradford-tech/npm-package-readme-mcp-server\n\nAn MCP server that exposes npm registry data — package READMEs, metadata, and search — to MCP-compatible AI clients.\n\n> This is a maintained fork of [`naoto24kawa/npm-package-readme-mcp-server`](https://github.com/naoto24kawa/npm-package-readme-mcp-server), republished under the `@bradford-tech` scope after the original was removed from GitHub and npm. No functional changes from the upstream `0.1.4` release.\n\n## Install\n\n```bash\nnpm install -g @bradford-tech/npm-package-readme-mcp-server\n```\n\nAlso works with `pnpm add -g`, `yarn global add`, or via `npx` (no install needed).\n\n## Configure your MCP client\n\nAdd the server to your client's MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-package-readme\": {\n      \"command\": \"npm-package-readme-mcp-server\"\n    }\n  }\n}\n```\n\nOr run on demand with `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-package-readme\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bradford-tech/npm-package-readme-mcp-server\"]\n    }\n  }\n}\n```\n\n## Tools\n\nThe server exposes three tools to the connected client.\n\n### `get_readme_from_npm`\n\nFetches a package's README and extracts usage examples. Reads from the npm registry first, falls back to the linked GitHub repository.\n\n| Parameter          | Type    | Default    | Description                                                |\n| ------------------ | ------- | ---------- | ---------------------------------------------------------- |\n| `package_name`     | string  | —          | The npm package name (required).                           |\n| `version`          | string  | `\"latest\"` | Specific version or dist-tag.                              |\n| `include_examples` | boolean | `true`     | Parse and return usage examples extracted from the README. |\n\nExample call:\n\n```json\n{ \"package_name\": \"react\", \"version\": \"18.2.0\" }\n```\n\n### `get_package_info_from_npm`\n\nReturns package metadata and download statistics for the latest version.\n\n| Parameter                  | Type    | Default | Description                      |\n| -------------------------- | ------- | ------- | -------------------------------- |\n| `package_name`             | string  | —       | The npm package name (required). |\n| `include_dependencies`     | boolean | `true`  | Include runtime dependencies.    |\n| `include_dev_dependencies` | boolean | `false` | Include dev dependencies.        |\n\nExample call:\n\n```json\n{ \"package_name\": \"express\", \"include_dependencies\": true }\n```\n\n### `search_packages_from_npm`\n\nSearches the npm registry.\n\n| Parameter    | Type   | Default | Description                    |\n| ------------ | ------ | ------- | ------------------------------ |\n| `query`      | string | —       | Search text (required).        |\n| `limit`      | number | `20`    | Max results, 1–250.            |\n| `quality`    | number | —       | Minimum quality score, 0–1.    |\n| `popularity` | number | —       | Minimum popularity score, 0–1. |\n\nExample call:\n\n```json\n{ \"query\": \"testing framework\", \"limit\": 10 }\n```\n\n## How package data is fetched\n\n- Package metadata and READMEs come from `registry.npmjs.org`.\n- If the registry response has no README, the server resolves the `repository` field and fetches the README from the GitHub API.\n- Download statistics come from `api.npmjs.org/downloads`.\n- Responses are cached in memory (default TTL: 1 hour; search results: 10 minutes).\n\nGitHub anonymous API requests are rate-limited to 60/hour. The server logs a warning when no token is available but still works for low-volume use.\n\n## Configuration\n\nAll settings are optional environment variables, passed via your MCP client's `env` field (or your shell, when launching directly).\n\n| Variable          | Default | Description                                                                                                                            |\n| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `CACHE_TTL`       | `3600`  | Default cache TTL in **seconds** for `get_readme_from_npm` and `get_package_info_from_npm`. Search results have a fixed 10-minute TTL. |\n| `REQUEST_TIMEOUT` | `30000` | Per-request timeout in **milliseconds**, applied to npm registry and GitHub API calls.                                                 |\n| `GITHUB_TOKEN`    | —       | GitHub personal access token. Raises the GitHub API rate limit from 60/hour to 5000/hour.                                              |\n| `LOG_LEVEL`       | `INFO`  | One of `ERROR`, `WARN`, `INFO`, `DEBUG` (case-insensitive). Invalid values silently fall back to `INFO`. Logs are written to `stderr`. |\n\nExample, with a GitHub token:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-package-readme\": {\n      \"command\": \"npm-package-readme-mcp-server\",\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_...\"\n      }\n    }\n  }\n}\n```\n\n## Requirements\n\n- Node.js >= 20\n\n## Contributing\n\nIssues and pull requests welcome at [bradford-tech/npm-package-readme-mcp-server](https://github.com/bradford-tech/npm-package-readme-mcp-server). See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the developer setup.\n\n## License\n\nMIT. See [`LICENSE`](./LICENSE).\n","readmeFilename":"README.md"}