{
"markdown": "# NPM Sentinel MCP\n\n\n\n[](https://smithery.ai/server/@Nekzus/npm-sentinel-mcp)\n[](https://github.com/Nekzus/npm-sentinel-mcp/actions/workflows/publish.yml)\n[](https://www.npmjs.com/package/@nekzus/mcp-server)\n[](https://www.npmjs.com/package/@nekzus/mcp-server)\n[](https://www.npmjs.com/package/@nekzus/mcp-server)\n[](https://hub.docker.com/r/mcp/npm-sentinel)\n[](https://deepwiki.com/Nekzus/npm-sentinel-mcp)\n[](https://paypal.me/maseortega)\n\n
\n\nA powerful **Model Context Protocol (MCP v2)** server built on `@modelcontextprotocol/server` and `@modelcontextprotocol/core` (v2) that revolutionizes NPM package analysis through AI. Built to integrate seamlessly with Claude, Anthropic AI, and any MCP v2 compatible client, it provides real-time intelligence on package security, dependencies, and performance.\n\nThis server features **Modular ESM Architecture (`src/`)**, **Dual Output Protocol Returns (`content` + `structuredContent`)**, **Zod Output Schemas (`outputSchema`)**, **Embedded SVG Data URI Icons**, and **Real-Time Context Logging**.\n\n## Key Features\n\n- **MCP v2 Native Protocol**: Fully upgraded to MCP v2 with `outputSchema` Zod validation, dual `structuredContent` returning, and diagnostic context logging (`ctx.mcpReq.log`).\n- **Self-Contained Vector Icons**: Pre-configured SVG Data URIs (`data:image/svg+xml`) embedded across all 19 tools, resources, and prompts for enhanced client UI presentation.\n- **Advanced Security Scanning**: Recursive dependency checks powered by Google's `deps.dev` and OSV.dev, ecosystem awareness, and accurate version resolution.\n- **Smart Alternatives Filtering (`npmAlternatives`)**: Intelligent search based on functional domain keywords with strict ecosystem plugin/extension filtering (e.g., excludes `express-rate-limit` when searching for alternatives to `express`).\n- **Strict Input Validation & Batch Rate Control**: Input sanitization via Zod against Path Traversal, SSRF, and Command Injection. Search queries (`npmSearch`) are capped at 100 characters and filtered for control characters. Batch analysis tools enforce a strict cap of 25 packages per request to prevent registry enumeration DoS.\n- **Dependency & Transitive Mapping**: Complete dependency tree analysis mapping through `deps.dev`.\n- **Package Quality & Maintenance Metrics**: Real-time scoring using OpenSSF Scorecard, GitHub repository metrics, and npms.io.\n- **Download Trends & Performance**: Real-time download statistics and bundle size analysis.\n- **Smart SemVer Shorthand & Range Resolution**: Transparently resolves major version shorthands, prefixes, and ranges (e.g., `express@2`, `express@v4`, `zod@3.x`, `react@^18`, `lodash@~4.17`) to the highest matching release without failing on missing exact version keys.\n- **Indirect Prompt Injection Defense (OWASP LLM01)**: All tools returning raw 3rd-party Markdown/text (`npmPackageReadme`, `npmChangelogAnalysis`) wrap untrusted content in `` tags, attach `_meta.untrustedExternalContent = true` flags, and enforce strict tool schema warnings.\n- **Efficient Caching System**: Automated cache invalidation on workspace lockfile changes (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`) with manual bypass (`ignoreCache: true`).\n\n## Security & OWASP LLM01 Compliance\n\nThis server implements **Defense-in-Depth** controls aligned with OWASP LLM01:2025 (Indirect Prompt Injection):\n\n1. **XML Data Demarcation**: Content from external packages (`README.md`, GitHub changelogs, release notes) is wrapped inside `` tags so consuming LLM models distinguish untrusted data from instructions.\n2. **Metadata Signaling (`_meta`)**: Responses include `_meta.untrustedExternalContent = true` and `_meta.sources` arrays for programmatic client-side detection and policy enforcement.\n3. **Tool & Prompt Safety Warnings**: Tool descriptions and prompt definitions explicitly instruct LLM agents to treat documentation as passive data and ignore embedded execution commands.\n4. **Batch Size Capping & Query Sanitization**: All 18 multi-package analysis tools enforce a 25-package limit per request (`PackageListSchema`). Search queries are sanitized and capped at 100 characters (`SearchQuerySchema`).\n5. **Prototype Pollution Protection**: Enforces `Object.hasOwn()` checks on dictionary lookups (blocking reserved properties like `constructor` and `__proto__`).\n\nTo ensure data accuracy while maintaining high performance:\n- **Automatic Invalidation**: The cache is automatically invalidated whenever `pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock` changes in your workspace.\n- **Force Refresh**: All tools accept an optional `ignoreCache: true` parameter to bypass the cache and force a fresh lookup from the NPM registry.\n\n### Example Usage (JSON-RPC)\n\n```json\n{\n \"name\": \"npmVersions\",\n \"arguments\": {\n \"packages\": [\"react\"],\n \"ignoreCache\": true\n }\n}\n```\n\n## Installation & Transports\n\n### Dual-Era MCP Architecture (v1 `2025-11-25` + v2 `2026-07-28`)\n\nThis MCP server features native **Dual-Era Protocol Compatibility**, seamlessly serving both modern MCP v2 clients (`2026-07-28`) and legacy MCP v1 clients (`2025-11-25`) out of the box across both **STDIO** and **Streamable HTTP** transports:\n\n- **STDIO Mode (`npx @nekzus/mcp-server`)**: Powered by `serveStdio({ legacy: \"serve\" })`. Handles modern `server/discover` probes sessionlessly and conjoins seamlessly with legacy `initialize` handshakes for local execution (Claude Desktop, Cursor, Docker).\n- **Streamable HTTP / SSE Mode (`@nekzus/mcp-server/http`)**: Powered by `createMcpHandler({ legacy: \"stateless\" })`. Designed for serverless and web-standard runtimes (Cloudflare Workers, Hono, Express, Vercel API Routes, Smithery.ai).\n\n**Example: Mounting HTTP Handler (Cloudflare Workers / Hono / Express)**\n```typescript\nimport { createMcpHttpHandler } from '@nekzus/mcp-server/http';\n\nconst handleRequest = createMcpHttpHandler();\n\nexport default {\n async fetch(request, env, ctx) {\n return handleRequest(request);\n }\n};\n```\n\n**Development Commands:**\n```bash\n# Install dependencies\npnpm install\n\n# Compile TypeScript to dist/\npnpm run build\n\n# Start STDIO server (Dual-Era)\npnpm run start\n\n# Development server with Smithery CLI playground\npnpm run dev\n\n# Run full unit and integration test suite (238 tests)\npnpm test -- --run\n\n# Run full E2E tarball verification\nnode __tests__/full-e2e-pack-validation.js\n```\n\n### Install in VS Code / Cursor\n\nAdd this to your VS Code / Cursor MCP configuration:\n\n```json\n{\n \"inputs\": [],\n \"servers\": {\n \"npm-sentinel\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@nekzus/mcp-server@latest\"]\n }\n }\n}\n```\n\n### Install in Claude Desktop\n\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"npm-sentinel\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@nekzus/mcp-server@latest\"]\n }\n }\n}\n```\n\n**Configuration File Locations:**\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n### Smithery.ai Deployment\n\n```json\n{\n \"mcpServers\": {\n \"npm-sentinel\": {\n \"type\": \"http\",\n \"url\": \"https://smithery.ai/server/@Nekzus/npm-sentinel-mcp\"\n }\n }\n}\n```\n\n### Docker Usage\n\n```bash\n# Build Docker image\ndocker build -t nekzus/npm-sentinel-mcp .\n\n# Run with local volume mount\ndocker run -i --rm -w /projects -v ${PWD}:/projects nekzus/npm-sentinel-mcp node dist/index.js\n```\n\n### Web Standard Streamable HTTP & Cloudflare Workers Integration\n\nThe package exports `createMcpHttpHandler` and `WebStandardStreamableHTTPServerTransport` for serverless platforms (Cloudflare Workers, Hono, Vercel, Express, Fastify, Next.js API routes) requiring official Web Standard Streamable HTTP transport under MCP v2:\n\n```typescript\nimport { createMcpHttpHandler } from '@nekzus/mcp-server/http';\n\nconst handleMcpRequest = createMcpHttpHandler();\n\nexport default {\n async fetch(request: Request): Promise {\n return handleMcpRequest(request);\n },\n};\n```\n\n**100% MCP v2 Compliance**: Powered by `WebStandardStreamableHTTPServerTransport`, this handler natively activates all 3 MCP primitives (**Tools**, **Resources**, and **Prompts**) with peak performance, SSE streaming support, and full Web Standard `Request` $\\rightarrow$ `Response` compatibility.\n\n\n## Configuration\n\nThe server supports the following configuration parameters:\n\n| Environment Variable | Config Object Property | Default | Description |\n| -------------------- | ---------------------- | ------- | ----------- |\n| `NPM_REGISTRY_URL` | `config.NPM_REGISTRY_URL` | `https://registry.npmjs.org` | URL of the NPM registry to use for all requests |\n\n---\n\n## MCP Server Capabilities (v2 API)\n\nAll tool responses conform to the MCP v2 dual output format, providing both human-readable text in `content` and parsed JSON objects in `structuredContent`:\n\n```json\n{\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"{\\n \\\"queryPackages\\\": [\\\"express\\\"],\\n \\\"results\\\": [...]\\n}\"\n }\n ],\n \"structuredContent\": {\n \"queryPackages\": [\"express\"],\n \"results\": [...]\n }\n}\n```\n\n### Server Resources\n\nAccessible via MCP `readResource` requests:\n\n- `doc://server/readme`\n - **Description**: Main documentation file for NPM Sentinel MCP server.\n - **MIME Type**: `text/markdown`\n - **Icon**: Embedded Document SVG Data URI.\n- `doc://mcp/specification`\n - **Description**: Complete Model Context Protocol specification file (`llms-full.txt`).\n - **MIME Type**: `text/plain`\n - **Icon**: Embedded Document SVG Data URI.\n\n### Server Prompts\n\nAccessible via MCP `getPrompt` requests:\n\n- `analyze-package`\n - **Description**: Generates a comprehensive prompt template for AI analysis of an NPM package including security, performance, dependencies, and health metrics.\n - **Arguments**: `package` (string, required)\n - **Icon**: Embedded Security SVG Data URI.\n\n---\n\n### Tools Catalog (19 Tools)\n\nAll 19 tools define `inputSchema`, `outputSchema`, `annotations` (`title`, `readOnlyHint`), and `icons`:\n\n#### 1. `npmLatest`\n- Get latest version information, release dates, SRI integrity hashes, and dist-tags.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 2. `npmVersions`\n- Get full version history with release dates and deprecation statuses.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 3. `npmDeps`\n- Complete dependency tree analysis including direct dependencies and full transitive graph mapping via `deps.dev`.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 4. `npmTypes`\n- Verify TypeScript support (native `index.d.ts` declaration files vs `@types/*` DefinitelyTyped packages).\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 5. `npmSize`\n- Package bundle size, minified size, and gzip impact analysis.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 6. `npmVulnerabilities`\n- Instant transitive vulnerability scanning powered by Google's `deps.dev` and OSV.dev advisories.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 7. `npmTrends`\n- Historical download statistics over customizable time ranges (`last-week`, `last-month`, `last-year`).\n- **Input**: `packages` (`string[]`), `period` (`\"last-week\"` \\| `\"last-month\"` \\| `\"last-year\"`), `ignoreCache` (`boolean`, optional)\n\n#### 8. `npmCompare`\n- Side-by-side metric comparison across multiple packages.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 9. `npmMaintainers`\n- List of package maintainers, public emails, and publishing activity.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 10. `npmScore`\n- Consolidated score combining quality, popularity, maintenance, and OpenSSF Scorecard.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 11. `npmPackageReadme`\n- Retrieve full formatted raw README markdown content from NPM registry / CDN.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 12. `npmSearch`\n- Search NPM registry packages by query with rich metadata (scores, publisher, keywords).\n- **Input**: `query` (`string`), `limit` (`number`, optional)\n\n#### 13. `npmLicenseCompatibility`\n- Analyze license compatibility across multiple packages (MIT, Apache-2.0, GPL, etc.).\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 14. `npmRepoStats`\n- Repository statistics (GitHub stars, forks, open issues) combined with OpenSSF Scorecard checks.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 15. `npmDeprecated`\n- Detect deprecation status on package and recursive sub-dependencies.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 16. `npmChangelogAnalysis`\n- Extract release notes and GitHub release history.\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 17. `npmAlternatives`\n- Smart functional alternative suggestions filtering out ecosystem plugins (e.g. excludes `express-rate-limit` for `express`).\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 18. `npmQuality`\n- Package code quality score (0–1).\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n#### 19. `npmMaintenance`\n- Package maintenance activity score (0–1).\n- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)\n\n---\n\n## License\n\nThis MCP server is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n\nMIT © [nekzus](https://github.com/nekzus)",
"bytes": 14434,
"sha": "78b20e1ee59c9d03e10f0a0520c6ba16b4fda22af266e694ca6c5241be4bd367",
"repo_slug": "nekzus/npm-sentinel-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_ai_smithery_nekzus_npm_sentinel_mcp_a92a1833/readme"
}