npm package: @kohlarnhin/context-ex
Description: Smart Programming Specification Manager - AI-Optimized with 2 Super Tools
Author: kohlarnhin
Latest version: 1.0.1

# Context-Ex

**AI 编程规范管理器** - 让 AI 按照你的规范写代码

[![npm version](https://img.shields.io/npm/v/@kohlarnhin/context-ex.svg)](https://www.npmjs.com/package/@kohlarnhin/context-ex)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

## 这是什么？

Context-Ex 是一个 MCP（Model Context Protocol）服务器，为 Claude、GPT 等 AI 提供**编程规范管理**和**合规验证**能力。

**核心价值**：将你团队的编程规范、代码风格、架构约定等注入 AI 的工作流程，确保 AI 生成的代码符合你的标准。

## 亮点

### 1. Index-First 设计，省 Token

传统方式：把所有规范一次性塞给 AI → Token 爆炸

Context-Ex 方式：
```
specs.tags (标签列表，~500 tokens)
    ↓
specs.query (规范索引，无正文)
    ↓
specs.get (按需拉取正文)
```

### 2. 智能标签体系

65+ 内置标签，覆盖主流技术栈：

| 分类 | 示例标签 |
|------|----------|
| 语言 | `language:java`, `language:ts`, `language:sql` |
| 框架 | `framework:spring`, `framework:mybatis-plus` |
| 分层 | `layer:controller`, `layer:service`, `layer:dao` |
| 主题 | `topic:validation`, `topic:null-handling`, `topic:exceptions` |
| 策略 | `policy:no-side-effects`, `policy:user-confirmation` |

### 3. 合规验证闭环

代码修改后自动触发验证，输出相关规范清单，确保 AI 复核代码合规性。

## 安装

```bash
npm install @kohlarnhin/context-ex
```

## MCP 配置

### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "context-ex": {
      "command": "npx",
      "args": ["@kohlarnhin/context-ex"]
    }
  }
}
```

### 本地开发

```json
{
  "mcpServers": {
    "context-ex": {
      "command": "node",
      "args": ["/your/path/to/context-ex/dist/cli.js"]
    }
  }
}
```

## MCP 工具

Context-Ex 提供 **2 个精简工具**，共 **5 个 actions**：

### `specs` - 规范管理

| Action | 用途 | 输出 |
|--------|------|------|
| `tags` | 获取标签字典 | 标签名、描述、使用计数 |
| `query` | 搜索规范索引 | 编号、标题、摘要（无正文） |
| `get` | 获取规范正文 | 完整内容 |

### `validate` - 合规验证

| Action | 用途 | 输出 |
|--------|------|------|
| `check` | 触发合规检查 | 相关规范清单 |
| `status` | 查看验证状态 | 上次检查时间等 |

## 使用示例

```javascript
// 1. 获取所有标签
await specs({ action: "tags" });

// 2. 按标签搜索（支持多标签 OR 查询）
await specs({
  action: "query",
  params: { tags: ["language:java", "layer:service"] }
});

// 3. 获取规范正文
await specs({
  action: "get",
  params: { numbers: [1, 6, 12] }
});

// 4. 修改代码后验证合规性
await validate({
  action: "check",
  params: { currentFile: "src/UserService.java" }
});
```

## 工作流程

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│ specs.tags  │ ──▶ │ specs.query  │ ──▶ │ specs.get   │
│ (~500 tok)  │     │ (索引检索)    │     │ (按需拉取)   │
└─────────────┘     └──────────────┘     └─────────────┘
                                                │
                                                ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   完成任务   │ ◀── │ 修复违规代码  │ ◀── │ 编写/修改代码 │
└─────────────┘     └──────────────┘     └─────────────┘
       ▲                   ▲                    │
       │                   │                    ▼
       │            ┌──────────────┐     ┌─────────────┐
       └────────────│  存在违规？   │ ◀── │validate.check│
           (否)     └──────────────┘     └─────────────┘
                           │(是)
                           ▼
                    ┌──────────────┐
                    │ specs.get    │
                    │ (查看违规规范) │
                    └──────────────┘
```

## 数据存储

- **数据库**：SQLite
- **默认路径**：`~/.context-ex/specifications.db`
- **自定义路径**：设置环境变量 `CONTEXT_EX_DB_PATH`
- **只读模式**：设置环境变量 `CONTEXT_EX_READONLY=1`

## 本地开发

```bash
git clone https://github.com/kohlarnhin/context-ex.git
cd context-ex
npm install
npm run build
npm start
```

## 技术栈

- **运行时**：Node.js >= 18
- **协议**：MCP (Model Context Protocol)
- **数据库**：SQLite (better-sqlite3)
- **类型系统**：TypeScript + Zod

## 许可证

MIT