Nekzus-npm-sentinel-mcp

NPM Sentinel MCP

一款功能强大的 Model Context Protocol（MCP v2） 服务，基于 @modelcontextprotocol/server 和 @modelcontextprotocol/core（v2）构建，通过 AI 革新 NPM 包分析。它专为与 Claude、Anthropic AI 及任何兼容 MCP v2 的客户端无缝集成而打造，可实时提供包安全性、依赖项和性能方面的情报。

此服务具备 模块化 ESM 架构（src/）、双输出协议返回值（content + structuredContent）、Zod 输出架构（outputSchema）、嵌入式 SVG Data URI 图标和实时上下文日志记录。

主要功能

• MCP v2 原生协议：全面升级至 MCP v2，支持 outputSchema Zod 验证、双 structuredContent 返回值和诊断上下文日志记录（ctx.mcpReq.log）。
• 自包含矢量图标：所有 19 个工具、资源和提示词均内嵌预配置的 SVG Data URI（data:image/svg+xml），优化客户端 UI 展示效果。
• 高级安全扫描：借助 Google 的 deps.dev 和 OSV.dev 递归检查依赖项，识别生态系统信息并准确解析版本。
• 智能替代方案筛选（npmAlternatives）：基于功能领域关键词智能搜索，并严格筛选生态系统插件/扩展（例如，为 express 搜索替代方案时排除 express-rate-limit）。
• 严格的输入验证与批量请求速率控制：通过 Zod 清理输入，防范路径遍历、SSRF 和命令注入。搜索查询（npmSearch）限制为 100 个字符，并过滤控制字符。批量分析工具严格限制每次请求最多处理 25 个包，以防止枚举注册表导致的 DoS。
• 依赖项与传递依赖映射：通过 deps.dev 完整分析并映射依赖树。
• 包质量与维护指标：利用 OpenSSF Scorecard、GitHub 仓库指标和 npms.io 实时评分。
• 下载趋势与性能：提供实时下载统计数据和包体积分析。
• 智能 SemVer 简写与范围解析：自动将主版本简写、前缀和范围解析为符合条件的最高版本，不会因缺少精确版本键而失败（例如，express@2、express@v4、[email protected]、react@^18、lodash@~4.17）。
• 间接提示词注入防御（OWASP LLM01）：所有返回第三方原始 Markdown/文本的工具（npmPackageReadme、npmChangelogAnalysis）都会将不可信内容包裹在 <untrusted_external_content> 标签中，附加 _meta.untrustedExternalContent = true 标记，并强制显示严格的工具架构警告。
• 高效缓存系统：当工作区锁文件（pnpm-lock.yaml、package-lock.json、yarn.lock）发生变化时自动使缓存失效，也可手动绕过缓存（ignoreCache: true）。

安全性与 OWASP LLM01 合规性

此服务实现了符合 OWASP LLM01:2025（间接提示注入）的纵深防御控制：

1. XML 数据界定：来自外部软件包（README.md、GitHub 变更日志、发行说明）的内容会被包裹在 <untrusted_external_content source="..." package="..." type="..."> 标签中，以便使用该服务的大模型将不可信数据与指令区分开来。
2. 元数据标记（_meta）：响应包含 _meta.untrustedExternalContent = true 和 _meta.sources 数组，供客户端通过编程方式检测并执行策略。
3. 工具与提示词安全警告：工具描述和提示词定义会明确指示 LLM Agent 将文档视为被动数据，并忽略其中嵌入的执行命令。
4. 批次大小限制与查询净化：所有 18 个多软件包分析工具都会对每个请求施加 25 个软件包的上限（PackageListSchema）。搜索查询会经过净化，长度上限为 100 个字符（SearchQuerySchema）。
5. 原型污染防护：对字典查找强制执行 Object.hasOwn() 检查（阻止 constructor 和 __proto__ 等保留属性）。

为确保数据准确性，同时保持高性能：

• 自动失效：只要工作区中的 pnpm-lock.yaml、package-lock.json 或 yarn.lock 发生变化，缓存就会自动失效。
• 强制刷新：所有工具都接受可选参数 ignoreCache: true，用于绕过缓存并从 NPM 注册表重新查询。

使用示例（JSON-RPC）

{
  "name": "npmVersions",
  "arguments": {
    "packages": ["react"],
    "ignoreCache": true
  }
}

安装与传输方式

双时代 MCP 架构（v1 2025-11-25 + v2 2026-07-28）

此 MCP 服务具备原生的双时代协议兼容性，开箱即用，可通过 STDIO 和 Streamable HTTP 两种传输方式，无缝服务现代 MCP v2 客户端（2026-07-28）和旧版 MCP v1 客户端（2025-11-25）：

• STDIO 模式（npx @nekzus/mcp-server）：由 serveStdio({ legacy: "serve" }) 提供支持。可无会话处理现代 server/discover 探测，并与旧版 initialize 握手无缝结合，适用于本地执行（Claude Desktop、Cursor、Docker）。
• Streamable HTTP / SSE 模式（@nekzus/mcp-server/http）：由 createMcpHandler({ legacy: "stateless" }) 提供支持。面向无服务器和 Web 标准运行时（Cloudflare Workers、Hono、Express、Vercel API Routes、Smithery.ai）。

示例：挂载 HTTP 处理程序（Cloudflare Workers / Hono / Express）

import { createMcpHttpHandler } from '@nekzus/mcp-server/http';

const handleRequest = createMcpHttpHandler();

export default {
  async fetch(request, env, ctx) {
    return handleRequest(request);
  }
};

开发命令：

# 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

在 VS Code / Cursor 中安装

将以下内容添加到 VS Code / Cursor MCP 配置中：

{
  "inputs": [],
  "servers": {
    "npm-sentinel": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nekzus/mcp-server@latest"]
    }
  }
}

在 Claude Desktop 中安装

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "npm-sentinel": {
      "command": "npx",
      "args": ["-y", "@nekzus/mcp-server@latest"]
    }
  }
}

配置文件位置：

• 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 部署

{
  "mcpServers": {
    "npm-sentinel": {
      "type": "http",
      "url": "https://smithery.ai/server/@Nekzus/npm-sentinel-mcp"
    }
  }
}

Docker 用法

# 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 标准 Streamable HTTP 与 Cloudflare Workers 集成

该软件包导出 createMcpHttpHandler 和 WebStandardStreamableHTTPServerTransport，供无服务器平台（Cloudflare Workers、Hono、Vercel、Express、Fastify、Next.js API 路由）使用。这些平台需要在 MCP v2 下采用官方 Web 标准 Streamable HTTP 传输：

import { createMcpHttpHandler } from '@nekzus/mcp-server/http';

const handleMcpRequest = createMcpHttpHandler();

export default {
  async fetch(request: Request): Promise<Response> {
    return handleMcpRequest(request);
  },
};

100% 符合 MCP v2：该处理程序由 WebStandardStreamableHTTPServerTransport 提供支持，可原生启用全部 3 种 MCP 原语（工具、资源和提示词），具备出色性能、SSE 流式传输支持，并与 Web 标准 Request $\rightarrow$ Response 完全兼容。

配置

服务器支持以下配置参数：

环境变量	配置对象属性	默认值	描述
NPM_REGISTRY_URL	config.NPM_REGISTRY_URL	https://registry.npmjs.org	所有请求所用的 NPM 注册表 URL

---

MCP 服务功能（v2 API）

所有工具响应均遵循 MCP v2 双输出格式，同时在 content 中提供人类可读文本，并在 structuredContent 中提供已解析的 JSON 对象：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"queryPackages\": [\"express\"],\n  \"results\": [...]\n}"
    }
  ],
  "structuredContent": {
    "queryPackages": ["express"],
    "results": [...]
  }
}

服务器资源

可通过 MCP readResource 请求访问：

• doc://server/readme
  • 描述：NPM Sentinel MCP 服务的主要文档文件。
  • MIME 类型：text/markdown
  • 图标：嵌入式文档 SVG 数据 URI。
• doc://mcp/specification
  • 描述：完整的 Model Context Protocol 规范文件（llms-full.txt）。
  • MIME 类型：text/plain
  • 图标：嵌入式文档 SVG 数据 URI。

服务器提示词

可通过 MCP getPrompt 请求访问：

• analyze-package
  • 描述：生成全面的提示词模板，用于 AI 分析 NPM 包，包括安全性、性能、依赖项和健康度指标。
  • 参数：package（string，必需）
  • 图标：嵌入式安全 SVG 数据 URI。

---

工具目录（19 个工具）

全部 19 个工具均定义了 inputSchema、outputSchema、annotations（title、readOnlyHint）和 icons：

1. npmLatest

• 获取最新版本信息、发布日期、SRI 完整性哈希和 dist-tags。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

2. npmVersions

• 获取完整版本历史记录，包括发布日期和弃用状态。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

3. npmDeps

• 全面的依赖树分析，包括直接依赖项，以及通过 deps.dev 映射的完整传递依赖图。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

4. npmTypes

• 验证 TypeScript 支持情况（原生 index.d.ts 声明文件与 @types/* DefinitelyTyped 包）。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

5. npmSize

• 包的捆绑大小、压缩后大小和 gzip 影响分析。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

6. npmVulnerabilities

• 由 Google 的 deps.dev 和 OSV.dev 安全公告提供支持的即时传递依赖漏洞扫描。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

7. npmTrends

• 可自定义时间范围（last-week、last-month、last-year）的历史下载统计数据。
• 输入：packages（string[]）、period（"last-week" | "last-month" | "last-year"）、ignoreCache（boolean，可选）

8. npmCompare

• 对多个包的指标进行并排比较。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

9. npmMaintainers

• 列出包维护者、公开邮箱和发布活动。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

10. npmScore

• 综合质量、受欢迎程度、维护情况和 OpenSSF Scorecard 得出评分。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

11. npmPackageReadme

• 从 NPM 注册表 / CDN 获取完整格式化的原始 README Markdown 内容。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

12. npmSearch

• 按查询词搜索 NPM 注册表中的包，并获取丰富的元数据（评分、发布者、关键词）。
• 输入：query（string）、limit（number，可选）

13. npmLicenseCompatibility

• 分析多个包之间的许可证兼容性（MIT、Apache-2.0、GPL 等）。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

14. npmRepoStats

• 结合 OpenSSF Scorecard 检查，提供代码仓库统计信息（GitHub 星标、复刻、开放问题）。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

15. npmDeprecated

• 检测软件包及其递归子依赖的弃用状态。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

16. npmChangelogAnalysis

• 提取发行说明和 GitHub 发布历史。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

17. npmAlternatives

• 智能推荐功能相近的替代方案，并过滤掉生态系统插件（例如，不会为 express 推荐 express-rate-limit）。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

18. npmQuality

• 软件包代码质量评分（0–1）。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

19. npmMaintenance

• 软件包维护活动评分（0–1）。
• 输入：packages（string[]）、ignoreCache（boolean，可选）

---

许可证

此 MCP 服务采用 MIT 许可证授权。详情请参阅 LICENSE。

MIT © nekzus