# SVP-MCP

Semantic Voxel Protocol - MCP Server

SVP 的 Model Context Protocol 实现，让 AI 编辑器 (Cursor, Claude Code, Windsurf 等) 能够与 SVP 项目集成。

## 功能

- 📊 **项目状态查询** - 查看编译层级和文件状态
- 🔧 **AI 编译** - 从编辑器触发 L5→L1 编译
- 📋 **Block 列表** - 列出所有逻辑块
- 🔍 **Block 详情** - 查看特定块的实现代码
- 📁 **Resources** - 暴露项目上下文作为 MCP Resources

## 安装

```bash
npm install -g @semanticvoxelprotocol/mcp-server
```

## 配置

### Cursor

创建 `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "svp": {
      "command": "npx",
      "args": ["@semanticvoxelprotocol/mcp-server", "--project", "."]
    }
  }
}
```

### Claude Code

Claude Code 会自动发现 MCP servers，或手动添加：

```bash
# 在项目目录运行
npx @semanticvoxelprotocol/mcp-server --project .
```

### 其他编辑器

任何支持 MCP 的编辑器都可以使用 stdio 传输层连接：

```bash
svp-mcp --project /path/to/project
```

## 提供的 Tools

### `svp_status`

获取项目编译状态

```json
{
  "name": "svp_status",
  "arguments": {}
}
```

### `svp_compile`

AI 编译指定层级

```json
{
  "name": "svp_compile",
  "arguments": {
    "level": 5  // 5|4|3|2
  }
}
```

### `svp_compile_all`

AI 编译所有层级 (L5→L1)

```json
{
  "name": "svp_compile_all",
  "arguments": {}
}
```

### `svp_list_blocks`

列出逻辑块

```json
{
  "name": "svp_list_blocks",
  "arguments": {
    "level": 3  // 3|2|1, default: 3
  }
}
```

### `svp_get_block`

获取特定块内容

```json
{
  "name": "svp_get_block",
  "arguments": {
    "blockId": "validate_order_input",
    "level": 1  // 1|2, default: 1
  }
}
```

## 提供的 Resources

| URI | 描述 |
|-----|------|
| `svp://{project}/context` | 项目上下文和状态 |
| `svp://{project}/ir/5` | L5 蓝图 (YAML) |
| `svp://{project}/ir/4` | L4 架构流程 (YAML) |
| `svp://{project}/ir/3` | L3 领域模型 (YAML) |
| `svp://{project}/ir/1` | L1 实现代码 (TypeScript) |

## 使用示例

在 Cursor 或 Claude Code 中：

```
> 查看 SVP 项目状态
使用 svp_status 工具查询项目编译状态...

✅ L1 (6 files)
✅ L2 (6 files)  
✅ L3 (6 blocks)
✅ L4
✅ L5

> 列出所有逻辑块
使用 svp_list_blocks 工具...

L3 Logic Blocks (6):
  - validate_order_input: Validate Order Input
  - call_inventory_service: Call Inventory Service
  ...

> 查看 validate_order_input 的实现
使用 svp_get_block 工具...

// L1 Block: validate_order_input
export function validateOrderInput(request: OrderRequest): ValidationResult {
  // 完整实现代码...
}

> 重新编译 L5
使用 svp_compile 工具，level=5...

✅ Successfully compiled L5 → L4
```

## 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 测试运行
node dist/server.js --project ../template-ts
```

## 架构

```
┌─────────────────┐     ┌─────────────┐     ┌─────────────────┐
│   AI Editor     │────▶│  MCP Client │────▶│  SVP MCP Server │
│ (Cursor/Claude) │     │   (stdio)   │     │  (this package) │
└─────────────────┘     └─────────────┘     └────────┬────────┘
                                                      │
                           ┌─────────────────────────┘
                           ▼
                    ┌─────────────┐
                    │  SVP Core   │
                    │ AICompiler  │
                    └─────────────┘
```

## License

MIT