io.github.Nekzus/npm-sentinel-mcp
Advanced NPM analysis: Recursive security scanning, ecosystem awareness, and deep insights.
Open source Open in the app JSON README (API)
About
Advanced NPM analysis: Recursive security scanning, ecosystem awareness, and deep insights.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- nekzus
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.26.1
- Stars
- 18
- Forks
- 10
- Last push
- 2026-08-24T20:48:27Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:07
- Updated
- 2026-08-29 03:02:07
- Origin id
io.github.Nekzus/npm-sentinel-mcp
README
# NPM Sentinel MCP
<div align="center">
[](https://smithery.ai/server/@Nekzus/npm-sentinel-mcp)
[](https://github.com/Nekzus/npm-sentinel-mcp/actions/workflows/publish.yml)
[](https://www.npmjs.com/package/@nekzus/mcp-server)
[](https://www.npmjs.com/package/@nekzus/mcp-server)
[](https://www.npmjs.com/package/@nekzus/mcp-server)
[](https://hub.docker.com/r/mcp/npm-sentinel)
[](https://deepwiki.com/Nekzus/npm-sentinel-mcp)
[](https://paypal.me/maseortega)
</div>
A 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.
This 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**.
## Key Features
- **MCP v2 Native Protocol**: Fully upgraded to MCP v2 with `outputSchema` Zod validation, dual `structuredContent` returning, and diagnostic context logging (`ctx.mcpReq.log`).
- **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.
- **Advanced Security Scanning**: Recursive dependency checks powered by Google's `deps.dev` and OSV.dev, ecosystem awareness, and accurate version resolution.
- **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`).
- **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.
- **Dependency & Transitive Mapping**: Complete dependency tree analysis mapping through `deps.dev`.
- **Package Quality & Maintenance Metrics**: Real-time scoring using OpenSSF Scorecard, GitHub repository metrics, and npms.io.
- **Download Trends & Performance**: Real-time download statistics and bundle size analysis.
- **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.
- **Indirect Prompt Injection Defense (OWASP LLM01)**: All tools returning raw 3rd-party Markdown/text (`npmPackageReadme`, `npmChangelogAnalysis`) wrap untrusted content in `<untrusted_external_content>` tags, attach `_meta.untrustedExternalContent = true` flags, and enforce strict tool schema warnings.
- **Efficient Caching System**: Automated cache invalidation on workspace lockfile changes (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`) with manual bypass (`ignoreCache: true`).
## Security & OWASP LLM01 Compliance
This server implements **Defense-in-Depth** controls aligned with OWASP LLM01:2025 (Indirect Prompt Injection):
1. **XML Data Demarcation**: Content from external packages (`README.md`, GitHub changelogs, release notes) is wrapped inside `<untrusted_external_content source="..." package="..." type="...">` tags so consuming LLM models distinguish untrusted data from instructions.
2. **Metadata Signaling (`_meta`)**: Responses include `_meta.untrustedExternalContent = true` and `_meta.sources` arrays for programmatic client-side detection and policy enforcement.
3. **Tool & Prompt Safety Warnings**: Tool descriptions and prompt definitions explicitly instruct LLM agents to treat documentation as passive data and ignore embedded execution commands.
4. **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`).
5. **Prototype Pollution Protection**: Enforces `Object.hasOwn()` checks on dictionary lookups (blocking reserved properties like `constructor` and `__proto__`).
To ensure data accuracy while maintaining high performance:
- **Automatic Invalidation**: The cache is automatically invalidated whenever `pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock` changes in your workspace.
- **Force Refresh**: All tools accept an optional `ignoreCache: true` parameter to bypass the cache and force a fresh lookup from the NPM registry.
### Example Usage (JSON-RPC)
```json
{
"name": "npmVersions",
"arguments": {
"packages": ["react"],
"ignoreCache": true
}
}
```
## Installation & Transports
### Dual-Era MCP Architecture (v1 `2025-11-25` + v2 `2026-07-28`)
This 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:
- **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).
- **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).
**Example: Mounting HTTP Handler (Cloudflare Workers / Hono / Express)**
```typescript
import { createMcpHttpHandler } from '@nekzus/mcp-server/http';
const handleRequest = createMcpHttpHandler();
export default {
async fetch(request, env, ctx) {
return handleRequest(request);
}
};
```
**Development Commands:**
```bash
# Install dependencies
pnpm install
# Compile TypeScript to dist/
pnpm run build
# Start STDIO server (Dual-Era)
pnpm run start
# Development server with Smithery CLI playground
pnpm run dev
# Run full unit and integration test suite (238 tests)
pnpm test -- --run
# Run full E2E tarball verification
node __tests__/full-e2e-pack-validation.js
```
### Install in VS Code / Cursor
Add this to your VS Code / Cursor MCP configuration:
```json
{
"inputs": [],
"servers": {
"npm-sentinel": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@nekzus/mcp-server@latest"]
}
}
}
```
### Install in Claude Desktop
Add this to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"npm-sentinel": {
"command": "npx",
"args": ["-y", "@nekzus/mcp-server@latest"]
}
}
}
```
**Configuration File Locations:**
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
### Smithery.ai Deployment
```json
{
"mcpServers": {
"npm-sentinel": {
"type": "http",
"url": "https://smithery.ai/server/@Nekzus/npm-sentinel-mcp"
}
}
}
```
### Docker Usage
```bash
# Build Docker image
docker build -t nekzus/npm-sentinel-mcp .
# Run with local volume mount
docker run -i --rm -w /projects -v ${PWD}:/projects nekzus/npm-sentinel-mcp node dist/index.js
```
### Web Standard Streamable HTTP & Cloudflare Workers Integration
The 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:
```typescript
import { createMcpHttpHandler } from '@nekzus/mcp-server/http';
const handleMcpRequest = createMcpHttpHandler();
export default {
async fetch(request: Request): Promise<Response> {
return handleMcpRequest(request);
},
};
```
**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.
## Configuration
The server supports the following configuration parameters:
| Environment Variable | Config Object Property | Default | Description |
| -------------------- | ---------------------- | ------- | ----------- |
| `NPM_REGISTRY_URL` | `config.NPM_REGISTRY_URL` | `https://registry.npmjs.org` | URL of the NPM registry to use for all requests |
---
## MCP Server Capabilities (v2 API)
All tool responses conform to the MCP v2 dual output format, providing both human-readable text in `content` and parsed JSON objects in `structuredContent`:
```json
{
"content": [
{
"type": "text",
"text": "{\n \"queryPackages\": [\"express\"],\n \"results\": [...]\n}"
}
],
"structuredContent": {
"queryPackages": ["express"],
"results": [...]
}
}
```
### Server Resources
Accessible via MCP `readResource` requests:
- `doc://server/readme`
- **Description**: Main documentation file for NPM Sentinel MCP server.
- **MIME Type**: `text/markdown`
- **Icon**: Embedded Document SVG Data URI.
- `doc://mcp/specification`
- **Description**: Complete Model Context Protocol specification file (`llms-full.txt`).
- **MIME Type**: `text/plain`
- **Icon**: Embedded Document SVG Data URI.
### Server Prompts
Accessible via MCP `getPrompt` requests:
- `analyze-package`
- **Description**: Generates a comprehensive prompt template for AI analysis of an NPM package including security, performance, dependencies, and health metrics.
- **Arguments**: `package` (string, required)
- **Icon**: Embedded Security SVG Data URI.
---
### Tools Catalog (19 Tools)
All 19 tools define `inputSchema`, `outputSchema`, `annotations` (`title`, `readOnlyHint`), and `icons`:
#### 1. `npmLatest`
- Get latest version information, release dates, SRI integrity hashes, and dist-tags.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 2. `npmVersions`
- Get full version history with release dates and deprecation statuses.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 3. `npmDeps`
- Complete dependency tree analysis including direct dependencies and full transitive graph mapping via `deps.dev`.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 4. `npmTypes`
- Verify TypeScript support (native `index.d.ts` declaration files vs `@types/*` DefinitelyTyped packages).
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 5. `npmSize`
- Package bundle size, minified size, and gzip impact analysis.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 6. `npmVulnerabilities`
- Instant transitive vulnerability scanning powered by Google's `deps.dev` and OSV.dev advisories.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 7. `npmTrends`
- Historical download statistics over customizable time ranges (`last-week`, `last-month`, `last-year`).
- **Input**: `packages` (`string[]`), `period` (`"last-week"` \| `"last-month"` \| `"last-year"`), `ignoreCache` (`boolean`, optional)
#### 8. `npmCompare`
- Side-by-side metric comparison across multiple packages.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 9. `npmMaintainers`
- List of package maintainers, public emails, and publishing activity.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 10. `npmScore`
- Consolidated score combining quality, popularity, maintenance, and OpenSSF Scorecard.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 11. `npmPackageReadme`
- Retrieve full formatted raw README markdown content from NPM registry / CDN.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 12. `npmSearch`
- Search NPM registry packages by query with rich metadata (scores, publisher, keywords).
- **Input**: `query` (`string`), `limit` (`number`, optional)
#### 13. `npmLicenseCompatibility`
- Analyze license compatibility across multiple packages (MIT, Apache-2.0, GPL, etc.).
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 14. `npmRepoStats`
- Repository statistics (GitHub stars, forks, open issues) combined with OpenSSF Scorecard checks.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 15. `npmDeprecated`
- Detect deprecation status on package and recursive sub-dependencies.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 16. `npmChangelogAnalysis`
- Extract release notes and GitHub release history.
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 17. `npmAlternatives`
- Smart functional alternative suggestions filtering out ecosystem plugins (e.g. excludes `express-rate-limit` for `express`).
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 18. `npmQuality`
- Package code quality score (0–1).
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
#### 19. `npmMaintenance`
- Package maintenance activity score (0–1).
- **Input**: `packages` (`string[]`), `ignoreCache` (`boolean`, optional)
---
## License
This MCP server is licensed under the MIT License. See [LICENSE](LICENSE) for details.
MIT © [nekzus](https://github.com/nekzus)