book-source-rule-mcp

README.md
# 书源 MCP 规则解析引擎

[![npm version](https://img.shields.io/npm/v/book-source-rule-mcp.svg)](https://www.npmjs.com/package/book-source-rule-mcp)
[![CI](https://github.com/你的用户名/book-mcp/workflows/CI%20-%20Build%20and%20Test/badge.svg)](https://github.com/你的用户名/book-mcp/actions)
[![npm downloads](https://img.shields.io/npm/dm/book-source-rule-mcp.svg)](https://www.npmjs.com/package/book-source-rule-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个基于 MCP (Model Context Protocol) 的规则解析引擎，使用 TypeScript 开发。这是一个自动化创建书源的工具，专注于提供强大的规则解析功能。

## 快速开始

### 使用 npx（推荐）

无需安装，直接使用：

```bash
npx book-source-rule-mcp
```

### 全局安装

```bash
npm install -g book-source-rule-mcp
book-source-rule-mcp
```

### 作为依赖使用

```bash
npm install book-source-rule-mcp
```

## 功能特性

### 规则解析引擎
- 🔍 **规则解析** (`parse_rule`) - 解析单个规则并从源数据中提取内容
- ✅ **规则验证** (`validate_rule`) - 验证规则语法的正确性  
- 📦 **批量规则解析** (`parse_batch_rules`) - 批量处理多个规则

## 支持的选择器类型

### 1. CSS 选择器 (`@css:`)
使用 Cheerio 解析 HTML 内容

```javascript
@css:.title                // 选择 class="title" 的元素
@css:.content p            // 选择 .content 下的所有 p 元素
@css:#main-title           // 选择 id="main-title" 的元素
@css:h1,h2,h3             // 选择所有 h1、h2、h3 元素
```

### 2. JSON 路径 (`@json:`)
使用 JSONPath 查询 JSON 数据

```javascript
@json:$.data.title         // 获取 data.title 字段
@json:$.books[*].name      // 获取所有书籍的名称
@json:$..author            // 递归查找所有 author 字段
@json:$.items[0,2,5]       // 获取指定索引的元素
```

### 3. 正则表达式 (`@regex:`)
使用正则表达式模式匹配提取内容

```javascript
@regex:title:\s*(.+)       // 匹配 "title:" 后的内容
@regex:\d+                 // 匹配数字
@regex:第(\d+)章           // 匹配章节号
@regex:作者：(.+?)\\s      // 匹配作者信息
```

### 4. 文本匹配 (`@text:`)
简单的文本包含检查

```javascript
@text:标题                 // 检查是否包含 "标题"
@text:第一章               // 检查是否包含 "第一章"
@text:完结                 // 检查是否包含 "完结"
```

## 规则操作符

### 连接操作符 (`&&`)
连接多个选择器的结果

```javascript
"@css:.author && @css:.publisher"
// 结果: "作者名 出版社名"
```

### 回退操作符 (`||`)
提供备选规则，如果前一个失败则尝试下一个

```javascript
"@css:.main-title || @css:.title || @json:$.title"
// 依次尝试三个选择器，返回第一个成功的结果
```

### 正则清理操作符 (`##`)
使用正则表达式清理提取的结果

```javascript
"@css:.chapter-title ## \\s*第.*?章\\s*"
// 提取章节标题并清理格式
```

### 组合使用
多个操作符可以组合使用

```javascript
"@css:.title || @json:$.title && @css:.subtitle ## 副标题：\\s*"
// 获取标题，连接副标题，并清理副标题格式
```

## 使用示例

### 基本用法

```javascript
// 提取文章标题
await server.parse_rule({
  rule: "@css:h1.title",
  data: "<html><h1 class='title'>示例标题</h1></html>",
  dataType: "html"
});

// 提取 JSON 数据
await server.parse_rule({
  rule: "@json:$.book.title",
  data: '{"book": {"title": "示例书名", "author": "作者"}}',
  dataType: "json"
});
```

### 复杂规则示例

```javascript
// 书籍信息提取规则
const rules = [
  {
    name: "title",
    rule: "@css:.book-title || @json:$.title"
  },
  {
    name: "author", 
    rule: "@css:.author && @css:.publisher ## 出版社：\\s*"
  },
  {
    name: "chapters",
    rule: "@css:.chapter-list a ## 第\\s*(\\d+)\\s*章"
  }
];

await server.parse_batch_rules({
  rules: rules,
  data: htmlContent,
  dataType: "html"
});
```

## 安装和使用

### 安装依赖

```bash
pnpm install
```

### 构建项目

```bash
pnpm run build
```

### 运行服务器

```bash
pnpm start
```

### 开发模式

```bash
pnpm run dev
```

## MCP 工具列表

### parse_rule
解析单个规则

**参数:**
- `rule` (string): 规则字符串
- `data` (string): 源数据
- `dataType` (string): 数据类型 ("html" | "json" | "text")

### validate_rule
验证规则语法

**参数:**
- `rule` (string): 要验证的规则字符串

### parse_batch_rules
批量解析规则

**参数:**
- `rules` (array): 规则数组，每个包含 name 和 rule 字段
- `data` (string): 源数据
- `dataType` (string): 数据类型

## VS Code 配置

项目包含 VS Code MCP 配置文件 `.vscode/mcp.json`，可直接在 VS Code 中使用：

```json
{
  "mcpServers": {
    "book-mcp": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "."
    }
  }
}
```

## 技术栈

- **TypeScript** - 类型安全的开发
- **MCP SDK** - Model Context Protocol 支持
- **Cheerio** - HTML 解析和 CSS 选择器
- **JSONPath** - JSON 数据查询
- **Zod** - 运行时类型验证
- **pnpm** - 快速的包管理器

## 项目结构

```
book-mcp/
├── src/
│   ├── index.ts           # MCP 服务器主入口
│   ├── rule-engine.ts     # 规则解析引擎
│   └── types/
│       └── jsonpath.d.ts  # JSONPath 类型声明
├── dist/                  # 编译输出目录
├── .vscode/
│   └── mcp.json          # VS Code MCP 配置
├── .github/
│   └── copilot-instructions.md
├── package.json
├── tsconfig.json
└── README.md
```

## 相关文档

- [MCP 官方文档](https://modelcontextprotocol.io/)
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP 规范](https://spec.modelcontextprotocol.io/)
- [官方服务器示例](https://github.com/modelcontextprotocol/servers)

## 许可证

MIT License
This server cannot be deployed
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd
Maintenance

ActivityInactive
ResponsivenessSyncing
Resources

Need Help?
Related Servers