# CJ-MCP — Cangjie Project MCP Server

一个最小可用、可扩展的 **Model Context Protocol (MCP)** 服务器，用于在 IDE（如 Cursor）里为模型提供：
- **项目专有上下文**（模块化的设计文档与规范）
- **Cangjie/ArkTS 开发模板**（工具与提示模板）

它非常适合与 **Context7**（或任何“Cangjie 语法/标准库参考”的 MCP）**同时启用**：  
- Context7 负责**语言/语法/标准库**  
- CJ-MCP 负责**你项目的专有知识与流程**

---

## 目录结构详解

```
my_mcp_server/
├── server.py              # MCP 服务器主程序（FastMCP + stdio）
├── prompts.json           # 提示模板配置文件（可选）
├── README.md              # 本文件
├── resources/             # 暴露给模型的只读资料
│   ├── global/            # 全局通用文档
│   │   ├── CANGJIE_C_FFI_SUMMARY.md  # Cangjie-C FFI 使用总结
│   │   └── libs/          # 标准库文档（可选）
│   │       └── std/       # 标准库各模块文档
│   └── modules/           # 各模块专属文档（按模块拆分上下文）
│       ├── incremental engine/  # 增量引擎模块
│       │   ├── 增量引擎串讲.md
│       │   ├── 增量引擎调用流程总结.md
│       │   ├── 仓颉函数调用流程详解.md
│       │   ├── 仓颉增量引擎相关概念解析.md
│       │   ├── 仓颉状态变更失效和更新机制详解.md
│       │   └── Dependency系统对比分析.md
│       ├── ui/            # UI 模块
│       │   ├── CALLBACK_FFI_DESIGN.md
│       │   └── onClick_Callback_Flow_Analysis.md
│       └── serialization_deserialization/  # 序列化模块（待补充）
└── .cursor/               # Cursor 配置（在项目根目录，不在本仓库）
    └── mcp.json           # MCP 服务器配置
```

---



## 快速开始

### 环境准备（conda 或 python venv 都行）

```bash
# 任选其一

# (A) conda
conda create -n mcp-env python=3.11 -y
conda activate mcp-env
pip install -r requirements.txt

# (B) python venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 在仓库根运行
python server.py
# 成功的话会“静默挂起”——表示在 stdio 等待 MCP 客户端连接


### 在 Cursor 里注册 MCP

重要：`.cursor/mcp.json` 要放在你打开的项目根目录（与 `.git` 同层）。

在项目根目录创建 `.cursor/mcp.json`（如果不存在），添加以下配置：

```json
{
  "mcpServers": {
    "cj-mcp": {
      "command": "python",
      "args": ["/home/maxime/ws/my_mcp_server/server.py"],
      "env": {
        "PYTHONPATH": "/home/maxime/ws/my_mcp_server"
      }
    }
  }
}
```

**注意**：
- 将 `/home/maxime/ws/my_mcp_server/server.py` 替换为你的实际路径
- 如果使用虚拟环境，`command` 应指向虚拟环境中的 Python，例如：`"/path/to/.venv/bin/python"`
- 重启 Cursor 使配置生效

---

## 功能说明

### 资源（Resources）

CJ-MCP 提供以下资源，模型可以通过 MCP 协议访问：

#### 全局资源

- **`cj://syntax`** - 仓颉语法/规范汇总
  - 自动聚合 `resources/global/` 下所有 `.md` 文件
  - 包含 Cangjie-C FFI 使用总结等全局文档

- **`cj://global`** - 所有全局文档
  - 包含语法、风格指南、公共设计等
  - 支持子目录结构（如 `libs/std/` 下的标准库文档）

#### 模块资源

- **`proj://modules/{module}`** - 指定模块的全部文档
  - `module` 参数示例：`"incremental engine"`, `"ui"`, `"serialization_deserialization"`
  - 自动扫描模块目录下的所有 `.md` 文件并聚合
  - 支持中文模块名（如 `"incremental engine"`）

**使用示例**：
```
获取增量引擎模块文档：proj://modules/incremental engine
获取 UI 模块文档：proj://modules/ui
```

### 工具（Tools）
#### `summarize_module`

对指定模块的文档进行粗粒度摘要，按文件顺序截取前若干字符。

**参数**：
- `module` (str) - 模块名称
- `max_chars` (int, 默认: 12000) - 最大字符数

**返回**：以 `==== FILE:` 分隔的文档摘要

### 提示模板（Prompts）

#### `cj_module_dev`

针对某个模块的开发任务提示模板。

**参数**：
- `module` (str) - 模块名称
- `task` (str) - 具体任务描述

**使用场景**：当需要开发或修改某个模块的功能时，使用此 prompt 可以让模型：
1. 自动获取相关语法文档（从 Context7）
2. 自动获取项目全局约定（从 `cj://global`）
3. 自动获取模块专有文档（从 `proj://modules/{module}`）
4. 生成符合项目规范的代码

**示例**：
```
module = "incremental engine"
task = "把增量引擎的navigation补齐，帮我进行增量引擎开发"
```

#### `cj_module_summary`

总结模块设计的提示模板。

**参数**：
- `module` (str) - 模块名称

**返回内容**：
- 模块目标与边界
- 关键类型/类/组件
- 状态与事件流转
- 与其他模块的依赖关系
- 已知坑点与注意事项


## 使用示例

### 示例 1：使用 cj_module_dev prompt

在 Cursor 中，你可以直接调用 prompt：

```
请使用 cj_module_dev prompt，module = "incremental engine", 
task = "把增量引擎的navigation补齐，帮我进行增量引擎开发"
```

模型会自动：
1. 读取 `cj://global` 获取全局规范
2. 读取 `proj://modules/incremental engine` 获取增量引擎文档
3. 根据任务生成符合规范的代码或文档

### 示例 2：直接访问资源

模型可以直接请求资源：

```
请读取 cj://syntax 了解仓颉语法
请读取 proj://modules/ui 了解 UI 模块设计
```

### 示例 3：使用工具生成组件

```
请使用 gen_cj_component 工具生成一个名为 MyView 的组件
```

---

## 开发指南

### 添加新模块文档

1. 在 `resources/modules/` 下创建模块目录（支持中文名称）
2. 将模块相关的 `.md` 文档放入该目录
3. 文档会自动被 `proj://modules/{module}` 资源聚合

**示例**：
```bash
mkdir -p resources/modules/my_module
# 添加文档
echo "# My Module" > resources/modules/my_module/README.md
```

### 添加全局文档

1. 将文档放入 `resources/global/` 目录
2. 支持子目录结构（如 `libs/std/`）
3. 所有 `.md` 文件会自动被 `cj://syntax` 和 `cj://global` 资源聚合

### 扩展工具

在 `server.py` 中添加新的 `@mcp.tool()` 装饰器函数：

```python
@mcp.tool()
def my_custom_tool(param1: str, param2: int = 10) -> str:
    """
    工具描述。
    """
    # 实现逻辑
    return result
```

### 扩展提示模板

在 `server.py` 中添加新的 `@mcp.prompt()` 装饰器函数：

```python
@mcp.prompt()
def my_custom_prompt(context: str) -> str:
    """
    提示模板描述。
    """
    return f"""
    你的提示模板内容...
    [上下文] {context}
    """
```

---

## 依赖说明

### Python 依赖

主要依赖：
- `mcp` - Model Context Protocol 服务器框架（FastMCP）

**安装**：
```bash
pip install mcp
```

或创建 `requirements.txt`：
```
mcp>=0.1.0
```

然后安装：
```bash
pip install -r requirements.txt
```

### Python 版本

建议使用 Python 3.11 或更高版本。

---

## 常见问题

### Q: 如何验证 MCP 服务器是否正常工作？

A: 在 Cursor 中，打开 MCP 面板（通常通过命令面板），查看 `cj-mcp` 服务器状态。如果显示已连接，说明配置成功。

### Q: 模块名称支持中文吗？

A: 支持。模块名称可以是中文，例如 `"incremental engine"`。在访问资源时使用：`proj://modules/incremental engine`

### Q: 如何与 Context7 配合使用？

A: CJ-MCP 专注于项目专有知识，Context7 专注于语言语法和标准库。两者可以同时启用：
- Context7 提供：语法规则、标准库 API、语言特性
- CJ-MCP 提供：项目架构、模块设计、团队规范

### Q: 资源文件支持哪些格式？

A: 目前主要支持 Markdown (`.md`) 文件。其他格式的文件会被忽略。

### Q: 如何调试 MCP 服务器？

A: 可以直接运行 `python server.py`，服务器会通过 stdio 与客户端通信。如果出现错误，会在终端显示。

### Q: 虚拟环境中的 Python 路径如何配置？

A: 在 `.cursor/mcp.json` 中，`command` 字段应指向虚拟环境的 Python 可执行文件：
```json
{
  "command": "/path/to/.venv/bin/python",
  "args": ["/path/to/server.py"]
}
```

---

## 贡献

欢迎提交 Issue 和 Pull Request！

---

## 许可证

[根据项目实际情况填写]

---

## 更新日志

### v1.0.0
- 初始版本
- 支持全局资源和模块资源
- 提供组件生成工具
- 提供模块开发提示模板# CJ-MCP — Cangjie Project MCP Server