内容
# Nowledge MCP Server
这是 **official Nowledge MCP Server**
它通过 MCP 获取一个 web URL，抓取所有相关页面，将它们转换为 Markdown，并返回一个文档或按页面返回一个列表。
## Features
- 🌐 **Web-wide Fetching**：从任何公共 web URL 获取内容
- 🧹 **HTML Sanitization**：去除页眉、页脚、导航、脚本和广告
- 🔗 **Link Rewriting**：调整链接以在 Markdown 中工作
- 📄 **Multiple Output Formats**：获取一个文档或结构化页面
- 🚀 **Performance**：通过可调整的并发和深度进行快速爬取
- **NLP**：按库名称或关键字搜索
## Usage
你可以使用的提示：
```
nowledge fetch how can i use gpt-image-1 with "vercel ai" sdk
```
```
nowledge fetch how can i create new blocks in shadcn?
```
```
nowledge fetch i want to understand how X works
```
获取完整的文档（默认）
```
use nowledge https://some-website.com/shadcn-ui/ui
use nowledge multiple pages https://some-website.com/shadcn-ui/ui
```
单页
```
use nowledge fetch single page https://some-website.com/tailwindlabs/tailwindcss/2.2-theme-system
```
通过简写获取
```
use nowledge fetch tailwindlabs/tailwindcss
```
```
nowledge fetch library
nowledge fetch url
nowledge fetch <name>/<repo>
nowledge multiple pages ...
nowledge single page url ...
```
## Cursor
将其添加到 `.cursor/mcp.json` 文件中。
```
{
"mcpServers": {
"mcp-nowledge": {
"command": "npx",
"args": ["-y", "mcp-nowledge@latest"]
}
}
}
```
<img src="public/nowledge.jpg" alt="Nowledge Logo">
### MCP Tool Integration
该包注册了一个名为 `nowledge_fetch` 的工具，你可以将其与任何兼容 MCP 的客户端一起使用：
```json
{
"action": "nowledge_fetch",
"params": {
"url": "https://some-website.com/user/repo",
"mode": "aggregate",
"maxDepth": "1"
}
}
```
#### Parameters
- `url` (required)：网站或存储库的起始 URL
- `mode` (optional)：输出模式，"aggregate" 表示单个 Markdown 文档（默认），"pages" 表示结构化页面数据
- `maxDepth` (optional)：要抓取的页面的最大深度（默认值：10）
### Response Format
#### Success Response (Aggregate Mode)
```json
{
"status": "ok",
"data": "# Page Title\n\nPage content...\n\n---\n\n# Another Page\n\nMore content...",
"totalPages": 5,
"totalBytes": 25000,
"elapsedMs": 1200
}
```
#### Success Response (Pages Mode)
```json
{
"status": "ok",
"data": [
{
"path": "index",
"markdown": "# Home Page\n\nWelcome to the repository."
},
{
"path": "section/page1",
"markdown": "# First Page\n\nThis is the first page content."
}
],
"totalPages": 2,
"totalBytes": 12000,
"elapsedMs": 800
}
```
#### Error Response
```json
{
"status": "error",
"code": "FETCH_FAIL",
"message": "Failed to fetch content from the web"
}
```
#### Partial Success Response
```json
{
"status": "partial",
"data": "# Page Title\n\nPage content...",
"errors": [
{
"url": "https://some-website.com/user/repo/page2",
"reason": "HTTP error: 404"
}
],
"totalPages": 1,
"totalBytes": 5000,
"elapsedMs": 950
}
```
### Progress Events
使用该工具时，你将在抓取期间收到进度事件：
```
Fetched https://some-website.com/user/repo: 12500 bytes in 450ms (status: 200)
Fetched https://some-website.com/user/repo/page1: 8750 bytes in 320ms (status: 200)
Fetched https://some-website.com/user/repo/page2: 6200 bytes in 280ms (status: 200)
```
## Local Development - Installation
### Local Usage
```
{
"mcpServers": {
"mcp-nowledge": {
"command": "node",
"args": ["./bin/cli.mjs"]
}
}
}
```
### From Source
```bash
# Clone the repository
git clone https://github.com/instructa/nowledge.git
cd nowledge
# Install dependencies
npm install
# Build the package
npm run build
```
#### Direct API Calls
对于 HTTP 传输，你可以进行直接 API 调用：
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"id": "req-1",
"action": "nowledge_fetch",
"params": {
"url": "https://some-website.com/user/repo",
"mode": "aggregate"
}
}'
```
## Configuration
### Environment Variables
- `NOWLEDGE_MAX_CONCURRENCY`：最大并发请求数（默认值：5）
- `NOWLEDGE_REQUEST_TIMEOUT`：请求超时时间（毫秒）（默认值：30000）
- `NOWLEDGE_MAX_RETRIES`：失败请求的最大重试次数（默认值：3）
- `NOWLEDGE_RETRY_DELAY`：重试退避的基本延迟（毫秒）（默认值：250）
要配置这些，请在项目根目录中创建一个 `.env` 文件：
```
NOWLEDGE_MAX_CONCURRENCY=10
NOWLEDGE_REQUEST_TIMEOUT=60000
NOWLEDGE_MAX_RETRIES=5
NOWLEDGE_RETRY_DELAY=500
```
## Docker Deployment (Untested)
构建并运行 Docker 镜像：
```bash
# Build the image
docker build -t mcp-nowledge .
# Run with stdio transport (for development)
docker run -it --rm mcp-nowledge
# Run with HTTP transport (for production)
docker run -d -p 3000:3000 mcp-nowledge --http --port 3000
# Run with environment variables
docker run -d -p 3000:3000 \
-e NOWLEDGE_MAX_CONCURRENCY=10 \
-e NOWLEDGE_REQUEST_TIMEOUT=60000 \
mcp-nowledge --http --port 3000
```
## Development
```bash
# Install dependencies
pnpm install
# Run in development mode with stdio
pnpm run dev-stdio
# Run tests
pnpm test
# Run linter
pnpm run lint
# Build the package
pnpm run build
```
## Troubleshooting
### Common Issues
1. **Permission Denied**：如果在运行 CLI 时遇到 EACCES 错误，请确保使二进制文件可执行：
```bash
chmod +x ./node_modules/.bin/mcp-nowledge
```
2. **Connection Refused**：确保端口可用且未被防火墙阻止：
```bash
# Check if port is in use
lsof -i :3000
```
3. **Timeout Errors**：对于大型存储库，请考虑增加超时时间和并发性：
```
NOWLEDGE_REQUEST_TIMEOUT=60000 NOWLEDGE_MAX_CONCURRENCY=10 npx mcp-nowledge
```
## Contributing
欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。
## License
MIT
## Links
- GitHub: [instructa/nowledge](https://github.com/instructa/nowledge)
- X/Twitter: [@kregenrek](https://x.com/kregenrek)
- Bluesky: [@kevinkern.dev](https://bsky.app/profile/kevinkern.dev)
## Courses
- Learn Cursor AI: [Ultimate Cursor Course](https://www.instructa.ai/en/cursor-ai)
- Learn to build software with AI: [instructa.ai](https://www.instructa.ai)
## See my other projects:
* [AI Prompts](https://github.com/instructa/ai-prompts/blob/main/README.md) - Curated AI Prompts for Cursor AI, Cline, Windsurf and Github Copilot
* [codefetch](https://github.com/regenrek/codefetch) - Turn code into Markdown for LLMs with one simple terminal command
* [aidex](https://github.com/regenrek/aidex) A CLI tool that provides detailed information about AI language models, helping developers choose the right model for their needs.
连接信息
猜你喜欢
暂无推荐服务器