MCP项目文件
一个模型上下文协议(MCP)服务器,为JavaScript/TypeScript项目提供智能、上下文感知的文档查找。旨在与Cursor IDE和其他MCP兼容工具中的AI助手无缝协作。
这是什么?
此MCP服务器会自动检测您的项目使用哪些框架和库,然后为AI助手提供:
- 自动加载上下文:项目依赖关系和版本自动可供AI使用
- 智能文档工具:按需获取最新文档的特定框架工具
- 智能建议:AI可以在建议更改代码之前查看当前API文档
为什么这很有用?
AI助手可能拥有关于框架API的过时信息,特别是对于Nuxt UI等快速发展的框架(从v3到v4有突破性的变化)。此服务器可确保您的AI助手始终可以访问特定项目依赖关系的最新文档。
特性
- 🔍 自动检测:自动检测项目中的Nuxt、Vue、React和其他框架
- 🤖 自动发现:自动发现项目中任何npm包的文档
- 📚 动态文档:按需从官方来源获取最新文档
- 🎯 上下文感知:知道您正在使用哪些版本的依赖项
- 🧹 清洁输出:提取和格式化文档内容,以实现最佳的人工智能消费
- ⚡ 快速:重量轻,快速响应工具调用
- 🔌 可扩展:插件系统使添加对新框架的支持变得容易
安装
推荐:作为开发依赖项安装
在项目中安装,以便服务器自动检测您的依赖关系:```bash
npm install --save-dev mcp-project-docs
然后在Cursor IDE设置中进行配置(请参阅下面的配置)。
### 替代方案:使用npx
无需安装,但您需要手动指定项目路径:```bash
# The server will be downloaded and run on-demand
替代方案:全球安装```bash
npm install -g mcp-project-docs
### 来自源头```bash
git clone
cd mcp-project-docs
npm install
npm run build
npm link
配置
光标IDE
选项1:作为开发依赖项安装(推荐)
如果您已安装 mcp-project-docs 作为项目中的开发依赖项:```json
{
"mcpServers": {
"project-docs": {
"command": "npx",
"args": ["-y", "mcp-project-docs"]
}
}
}
**就是这样!** 服务器会自动检测您的项目 `package.json` 从当前工作目录。
#### 选项2:使用npx或全局安装
如果你正在使用 `npx` 在不进行本地安装或使用全局安装的情况下,您需要指定项目路径:```json
{
"mcpServers": {
"project-docs": {
"command": "npx",
"args": ["-y", "mcp-project-docs"],
"env": {
"PROJECT_PATH": "/absolute/path/to/your/project"
}
}
}
}
重要:替换 /absolute/path/to/your/project 带有项目目录的实际绝对路径(包含 package.json).
其他MCP客户端
根据客户的文档进行配置,确保:
- 命令:
npx -y mcp-project-docs(或mcp-project-docs如果全局安装) - 环境变量
PROJECT_PATH指向您的项目目录
支持的框架
目前支持
努克斯特
- ✅ Nuxt UI组件文档
- ✅ Nuxt框架文档
- ✅ 自动版本检测
- ✅ 重大变更警告(例如v3→ v4)
工具:
check_nuxt_ui_component:获取组件文档(例如,UButton、UCard)check_nuxt_feature:获取框架文档(例如,可组合文件、服务器API)
Vue
- ✅ Vue 3 API文档
- ✅ 成分API参考文献
- ✅ 组件API文档
工具:
check_vue_api:获取Vue API文档(例如,ref、computed、watch)
Next.js
- ✅ Next.js应用路由器文档
- ✅ 组件和功能的API参考
- ✅ 自动应用路由器检测(v13+)
工具:
check_nextjs_docs:获取Next.js文档check_nextjs_api:获取Next.js API引用(Next/image、Next/link等)
Angular
- ✅ Angular API文档
- ✅ 角度指南文档
- ✅ 角材料检测
工具:
check_angular_api:获取Angular API文档(组件、可注入等)check_angular_guide:获取Angular指南(路线、表单等)
Svelte/SvelteKit
- ✅ Svelte API文件
- ✅ SvelteKit功能文档
工具:
check_svelte_api:获取Svelte API文档check_sveltekit_feature:获取SvelteKit文档(路由、加载等)
Tailwind CSS
- ✅ 顺风CSS实用程序文档
- ✅ 插件检测(@tailwindcss/forms,排版)
工具:
check_tailwind_docs:获取顺风CSS文档(flex、网格、颜色等)
Express.js
- ✅ API Express文档
- ✅ 快速指南文档
工具:
check_express_api:获取API Express文档(应用程序、请求、res、路由器)check_express_guide:Fetch Express指南(路由、中间件等)
棱镜
- ✅ Prisma概念文档
- ✅ Prisma API参考
工具:
check_prisma_docs:获取Prisma文档(架构、客户端、迁移)check_prisma_reference:获取Prisma API引用
维特
- ✅ Vite配置文档
- ✅ 插件检测(React、Vue)
工具:
check_vite_docs:获取Vite文档(功能、配置、构建)
星的
- ✅ Astro文件
- ✅ 集成文档
- ✅ 集成检测(React、Vue、Svelte、Tailwind)
工具:
check_astro_docs:获取Astro文档(组件、内容集合)check_astro_integration:获取Astro集成文档
SolidJS
- ✅ SolidJS文档
- ✅ 路由器和SolidStart检测
工具:
check_solid_docs:获取SolidJS文档(反应性、信号)
混音
- ✅ 混音文件
- ✅ Remix API参考
工具:
check_remix_docs:获取Remix文档(路由、加载器、操作)check_remix_api:获取Remix API引用(useLoaderData等)
React(基础)
- ✅ React上下文和版本检测
- ⏳ React钩子文档(计划中)
插件系统已经到位,欢迎投稿!
自动发现(任何npm包)
除了内置插件,服务器 自动发现文档 使用智能多策略发现您项目中的任何npm包!
它是如何工作的:
自动发现系统使用复杂的5层策略来查找最佳文档:
- 已知文档URL (最高优先级)
- 50多个精选的热门软件包文档URL
- 确保VueUse、Pinia、TanStack Query等软件包获得其实际的文档站点
- 主页分析
- 检查包的主页是否是文档网站
- 过滤掉存储库链接(github,gitlab.com)
- 允许经常托管文档的GitHub页面(*.GitHub.io)
- 具有文档相关关键字(.dev、.io、docs、guide)的URL的置信度更高
- 常见文档模式 ⭐ 新
- 尝试
docs.{domain}子域名 - 尝试
{homepage}/docs路径 - 尝试
{homepage}/documentation路径 - 尝试
{homepage}/guide路径 - 尝试GitHub页面模式:
{org}.github.io/{repo} - 尝试阅读文档:
{package}.readthedocs.io - 在使用之前,实际验证每个URL是否存在!
- 主页内容分析 ⭐ 新
- 获取并解析主页HTML
- 在页面中查找文档链接
- 提取具有以下模式的链接
/docs,/documentation,/guide - 将相对URL转换为绝对URL
- 后备选项
- GitHub README(如果存储库可用)
- npm包页面(最后手段)
例子: 如果你的项目有 lodash 安装后,您将自动获得:```
AI: Let me check the lodash documentation for array methods...
[AI calls: check_lodash_docs({ topic: "array" })]
[Server returns: Lodash array documentation]
**是什么让它变得聪明:**
- ✅ **验证URL是否存在** -不返回断开的链接
- ✅ **分析实际内容** -解析主页以查找文档链接
- ✅ **尝试多种策略** -如果一个方法失败,则优雅地回退
- ✅ **缓存结果** -避免重复查找性能
- ✅ **信心评分** -告诉您找到的URL有多可靠
**支持的软件包包括:**
- 50多个受欢迎的软件包,包含精心策划的文档URL
- 任何具有可发现文档站点的包
- 使用常见文档托管模式的包(ReadTheDocs、GitHub Pages等)
- 主页上带有文档链接的软件包
**禁用自动发现:**```json
{
"mcpServers": {
"project-docs": {
"command": "npx",
"args": ["-y", "mcp-project-docs"],
"env": {
"PROJECT_PATH": "/path/to/project",
"AUTO_DISCOVERY": "false"
}
}
}
}
自定义文档
您可以通过创建配置文件为项目中未安装的包添加自定义文档。这有助于:
- 第三方服务和基于网络的文档(例如Apple MapKit JS、Google Maps API)
- 内部文件网站
- 您引用但不直接安装的软件包
创建配置文件:
创建任一 .mcp-project-docs.json 或 mcp-project-docs.json 在项目根目录中:```json
{
"packages": [
{
"name": "@apple/mapkit-js",
"docsUrl": "https://developer.apple.com/documentation/mapkitjs",
"description": "Apple MapKit JS - Interactive maps for web applications",
"version": "latest"
},
{
"name": "google-maps-api",
"docsUrl": "https://developers.google.com/maps/documentation/javascript",
"description": "Google Maps JavaScript API"
}
]
}
**配置格式:**
- `name` (必填):包标识符(可以是任何字符串,不需要匹配npm包)
- `docsUrl` (必填):文档的基本URL
- `description` (可选):人类可读的描述
- `version` (可选):版本字符串(默认为“自定义”)
配置后,您可以像使用任何其他软件包一样使用文档工具:```
AI: Let me check the Apple MapKit JS documentation for loading the library...
[AI calls: check_apple_mapkit_js_docs({ topic: "loading-the-latest-version-of-mapkit-js" })]
[Server returns: Apple MapKit JS documentation]
服务器将自动创建一个名为的工具 check_{sanitized_package_name}_docs 对于每个自定义包。
使用示例
在游标IDE中
配置后,AI助手自动访问:
资源(自动加载)
project://dependencies-包含版本的完整依赖关系列表project://context-框架特定注释和文档链接
工具(按需)
示例1:检查Nuxt UI组件```
AI: I need to use a button component. Let me check the current Nuxt UI Button API...
[AI calls: check_nuxt_ui_component({ component: "button" })]
[Server returns: Latest UButton documentation]
AI: Based on the current v4 API, here's the correct usage...
**示例2:检查Vue可组合**```
AI: Let me verify the ref() API before suggesting this code...
[AI calls: check_vue_api({ api: "ref" })]
[Server returns: Vue 3 ref documentation]
AI: According to the official docs...
工具说明
服务器提供了清晰、指导性的工具描述,以指导AI行为:
> 请查看最新的API文档以获取Nuxt UI组件。在建议或修改任何Nuxt UI部件代码(UButton、UCard、UModal等)之前使用此文档,以确保您拥有当前的v4 API
这有助于人工智能知道何时以及如何有效地使用每种工具。
运作原理
- 项目检测:阅读您的
package.json识别依赖关系和版本
- 当作为开发依赖项安装时,会自动检测您的项目目录
- 回落到PROJECT_PATH环境变量(如果需要) - 插件激活:激活主要框架(Nuxt、Vue、React等)的内置插件
- 自动发现:扫描npm注册表以查找剩余包的文档URL
- 动态插件创建:为发现的包动态创建插件
- 资源加载:自动将项目上下文提供给AI
- 工具注册:登记特定框架的文件工具
- 按需获取:在AI需要时获取和解析文档
- 清洁提取:将格式化的相关内容返回给AI
为什么安装为开发依赖?
安装 mcp-project-docs 因为项目中的开发依赖有几个优点:
- ✅ 自动路径检测:无需手动配置
PROJECT_PATH - ✅ 项目特定:每个项目都可以有自己的版本
- ✅ 版本控制:将版本锁定在您的
package.json - ✅ 团队一致性:团队中的每个人都使用相同的配置
- ✅ 更简单的设置:只是
npm install --save-dev mcp-project-docs并配置MCP
建筑```
src/
├── index.ts # Main MCP server
├── parsers/
│ └── html.ts # HTML content extraction
├── discovery/
│ ├── package-scanner.ts # npm registry metadata fetcher
│ ├── docs-crawler.ts # Documentation site crawler
│ ├── dynamic-plugin.ts # Auto-generated plugins
│ └── index.ts # Discovery module exports
└── plugins/
├── nuxt.ts # Nuxt-specific tools
├── vue.ts # Vue-specific tools
└── react.ts # React-specific tools (stub)
### 插件系统
每个插件实现:
- `detect(dependencies)`:如果框架存在,则返回true
- `getTools()`:返回MCP工具定义
- `handleToolCall(name, args)`:处理工具执行
- `getContext(dependencies)`:返回markdown上下文
这使得添加新框架变得简单。
## 添加对新框架的支持
1. 在中创建新的插件文件 `src/plugins/`
1. 实施 `Plugin` 接口
1. 为框架添加检测逻辑
1. 用清晰的描述定义工具
1. 实施工具处理程序
1. 在中注册插件 `src/index.ts`
骨架示例:```typescript
import { Plugin, ToolDefinition } from './nuxt.js';
import { HtmlParser } from '../parsers/html.js';
export class MyFrameworkPlugin implements Plugin {
private parser = new HtmlParser();
detect(dependencies: Record): boolean {
return 'my-framework' in dependencies;
}
getTools(): ToolDefinition[] {
return [
{
name: 'check_my_framework_api',
description: 'Clear description that tells AI when to use this tool',
inputSchema: {
type: 'object',
properties: {
api: { type: 'string', description: 'API to check' },
},
required: ['api'],
},
},
];
}
async handleToolCall(name: string, args: Record): Promise {
// Implementation
}
getContext(dependencies: Record): string {
return '## My Framework\n\nContext information...';
}
}
故障排除
服务器无法启动
问题:关于丢失的错误 package.json
解决方案:确保 PROJECT_PATH 环境变量指向包含以下内容的目录 `package.json````bash
Check if PROJECT_PATH is set correctly
echo $PROJECT_PATH
ls $PROJECT_PATH/package.json
### 没有可用的工具
**问题**:AI看不到任何文档工具
**解决方案**:
1. 检查您的项目是否安装了支持的框架
1. 验证 `package.json` 包括以下依赖关系 `nuxt`, `vue`,或 `react`
1. 配置更改后重新启动MCP客户端
### 文档获取失败
**问题**:工具返回“获取失败”错误
**解决方案**:
1. 检查互联网连接
1. 验证文档URL是否可访问
1. 某些公司网络可能会阻止某些域
### 返回了错误的文档
**问题**:文档与您的版本不匹配
**解决方案**:服务器从官方网站获取最新文档。如果您的依赖版本已过时,请考虑更新它,或手动检查特定版本的文档。
## 发展
### 先决条件
- Node.js 20+
- npm或纱线
- 多普勒CLI (用于秘密管理)
### 设置```bash
# Clone the repository
git clone https://github.com/loganrenz/nardocs.git
cd nardocs
# Install dependencies
npm install
# Setup Doppler (for secrets management)
doppler login
doppler setup --project nardocs --config dev
# Build
npm run build
# Watch mode (for development)
doppler run -- npm run dev
# Run tests
doppler run -- npm run test
# Run tests with coverage
doppler run -- npm run test:coverage
有关更多详细信息,请参阅:
- 贡献.md -贡献指南
- .github/DOPPLER_SETUP.md -秘密管理设置
测试```bash
Build the server
npm run build
Test with a sample project
PROJECT_PATH=/path/to/test/project node build/index.js
### 项目结构
- `src/`:TypeScript源代码
- `build/`:编译的JavaScript输出
- `package.json`:项目配置
- `tsconfig.json`:TypeScript配置
## 需求
- Node.js 20或更高版本
- 一个项目 `package.json`
- 互联网连接(用于获取文档)
## 许可证
麻省理工学院
## 贡献
欢迎投稿!我们特别感兴趣的是:
- 🎯 新框架插件
- 🔧 改进了文档网站的HTML解析
- 💾 缓存频繁访问的文档
- 📱 离线文档支持
- 🎨 更好的错误消息和建议
请看 贡献.md 详细指南。
### 贡献者快速入门```bash
# Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/nardocs.git
cd nardocs
# Install dependencies
npm install
# Make your changes and test
npm run test
npm run lint
# Commit using conventional commits
git commit -m "feat: add support for new framework"
# Push and create a PR
git push origin your-branch-name
学分
内置:
- @模型上下文协议/sdk -MCP协议实现
- 再见 -HTML解析
- 节点获取 -HTTP请求
