# OFC-AI

[![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

OFC-AI 是一个基于 MCP (Model Context Protocol) 的后端服务，专为 AI 辅助编程而设计。它提供了一套完整的工具集，用于项目规范初始化、需求文档生成、PRP（产品需求提示）文档管理以及思维处理等功能。

## 🚀 特性

- **MCP 集成**: 完全兼容 Model Context Protocol，可与支持 MCP 的 AI 客户端无缝集成
- **项目规范管理**: 自动生成和管理项目开发规范
- **需求文档生成**: 提供标准化的需求文档模板和生成工具
- **PRP 文档系统**: 支持产品需求提示（Product Requirements Prompt）文档的创建和执行
- **思维处理工具**: 结构化的思维过程管理和输出格式化
- **使用记录追踪**: 自动记录工具使用情况，便于分析和优化

## 📦 安装

### 使用 uv（推荐）

```bash
uv add ofc-ai
```

### 使用 pip

```bash
pip install ofc-ai
```

## 🛠️ 使用方法

### 作为 MCP 服务器运行

```bash
# 直接运行
uv run ofc-ai

# 或者使用 Python 模块方式
python -m ofc_ai.main
```

### MCP 客户端配置

在你的 MCP 客户端配置文件中添加以下配置：

```json
{
  "mcpServers": {
    "ofc-ai": {
      "autoApprove": [
        "execute_ofc",
        "execute_prp",
        "init_project_rules",
        "process_thought",
        "log_report",
        "java_fast_coding",
        "skills_expert"
      ],
      "timeout": 600,
      "command": "uvx",
      "type": "stdio",
      "transportType": "stdio",
      "args": [
        "--refresh",
        "--index-url",
        "https://mirrors.aliyun.com/pypi/simple/",
        "ofc-ai"
      ],
      "disabled": false
    }
  }
}
```

## 🔧 可用工具

### 1. init_project_rules
- **描述**: 初始化项目规范模板
- **参数**: 无
- **返回**: 项目规范模板内容
- **用途**: 为新项目生成标准化的开发规范和最佳实践指南

### 2. execute_ofc
- **描述**: 统一的 OFC 工具 - 整合了初始化需求文档和生成 PRP 文档的功能
- **参数**:
  - `action` (string): 执行动作类型
    - `'init_doc'`: 初始化需求文档
    - `'generate_prp'`: 生成 PRP 文档
  - `feature_file` (string, optional): 功能需求文件路径（当 action='generate_prp' 时必填）
- **返回**: 根据动作类型返回相应的文档生成指导
- **用途**:
  - `init_doc`: 生成标准化的需求文档模板，帮助团队规范需求描述
  - `generate_prp`: 将功能需求转换为结构化的 PRP 文档，指导 AI 进行精确的功能实现
- **使用示例**:
  - 初始化需求文档: `execute_ofc(action="init_doc")`
  - 生成 PRP: `execute_ofc(action="generate_prp", feature_file="INITIAL.md")`

### 3. execute_prp
- **描述**: 根据 PRP 文件生成执行指南
- **参数**: 
  - `prpFile` (string): PRP 文件路径
- **返回**: 完整的执行步骤指南
- **用途**: 为 PRP 文档提供详细的执行流程和验证步骤

### 5. process_thought
- **描述**: 处理单一思维并返回格式化输出
- **参数**: 
  - `thought` (string): 思维内容
  - `thought_number` (int): 当前思维编号
  - `total_thoughts` (int): 预计总思维数量
  - `next_thought_needed` (bool): 是否需要下一步思维
  - `stage` (string): 思维阶段
  - `tags` (array, optional): 思维标签
  - `axioms_used` (array, optional): 使用的公理
  - `assumptions_challenged` (array, optional): 挑战的假设
- **返回**: 格式化的思维处理输出
- **用途**: 结构化管理复杂的思维过程，提供清晰的思考路径

### 6. log_report
- **描述**: 上报工具使用记录
- **参数**: 
  - `work_dir` (string): 工作目录路径
  - `tool_type` (string): 使用的工具类型
  - `skill_name` (string, optional): 技能名称
- **返回**: 记录确认信息
- **用途**: 追踪工具使用情况，便于分析和优化

### 7. java_fast_coding
- **描述**: Java 快速编码工具，基于简单描述生成 Java 后端代码
- **参数**:
  - `user_input` (string): 用户简单描述的需求
  - `repo_path` (string): Java 项目根目录（绝对路径）
  - `target_file` (string, optional): 目标文件路径
  - `modify_type` (string, optional): 修改类型
  - `design_doc_path` (string, optional): 设计文档路径
- **返回**: Java 代码生成指导
- **用途**: 快速生成 REST API、数据模型、RPC 服务、业务服务等 Java 代码

### 8. skills_expert
- **描述**: 智能 skills 专家，自动匹配并执行相应的技能
- **参数**:
  - `requirements` (string, optional): 用户需求描述
  - `requirements_file` (string, optional): 需求文件路径
  - `repo_path` (string): Git 仓库目录（绝对路径）
- **返回**: 技能执行指导
- **用途**: 根据需求自动匹配最适合的技能并执行

## 📁 项目结构

```
ofc_ai/
├── __init__.py                 # 包初始化文件
├── main.py                     # MCP 服务器主程序
├── prompts/                    # 提示词模板目录
│   ├── __init__.py
│   ├── CreateFeatureProjectRules.md
│   ├── init_project_rules.py
│   ├── init_requirements_doc.py
│   └── prp_base.md
├── tools/                      # 工具实现目录
│   ├── __init__.py
│   ├── init_project_rules.py
│   └── init_requirements_doc.py
└── utils/                      # 工具函数目录
    ├── __init__.py
    ├── file_reader.py
    ├── file_utils.py
    ├── git_info.py
    ├── loader.py
    ├── log.py
    ├── template.py
    ├── user_info.py
    └── version.py
```

## 🔗 依赖项

- **Python**: >=3.13
- **GitPython**: >=3.1.45 (Git 操作支持)
- **httpx**: >=0.28.1 (HTTP 客户端)
- **keyring**: >=25.6.0 (密钥管理)
- **mcp[cli]**: >=1.18.0 (MCP 协议支持)
- **pipx**: >=1.8.0 (Python 应用管理)
- **pydantic**: >=2.0.0 (数据验证)

## 🚀 开发

### 环境设置

1. 克隆仓库：
```bash
git clone <repository-url>
cd ofc-ai
```

2. 安装依赖：
```bash
uv sync
```

3. 运行开发服务器：
```bash
uv run python -m ofc_ai.main
```

### 测试

```bash
# 运行测试
uv run pytest

# 运行测试并生成覆盖率报告
uv run pytest --cov=ofc_ai
```

## 📋 使用示例

### 1. 初始化项目规范

```python
# 通过 MCP 客户端调用
{
  "method": "tools/call",
  "params": {
    "name": "init_project_rules",
    "arguments": {}
  }
}
```

### 2. 使用 execute_ofc 工具

```python
# 初始化需求文档
{
  "method": "tools/call",
  "params": {
    "name": "execute_ofc",
    "arguments": {
      "action": "init_doc"
    }
  }
}

# 生成 PRP 文档
{
  "method": "tools/call",
  "params": {
    "name": "execute_ofc",
    "arguments": {
      "action": "generate_prp",
      "feature_file": "features/user-auth.md"
    }
  }
}
```

### 3. 处理思维过程

```python
# 通过 MCP 客户端调用
{
  "method": "tools/call",
  "params": {
    "name": "process_thought",
    "arguments": {
      "thought": "需要分析用户认证系统的安全性",
      "thought_number": 1,
      "total_thoughts": 3,
      "next_thought_needed": true,
      "stage": "分析",
      "tags": ["安全", "认证"]
    }
  }
}
```

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 👨‍💻 作者

**hanshuai**

## 🔗 相关链接

- [Model Context Protocol](https://modelcontextprotocol.io) - 了解更多关于 MCP 协议
- [uv](https://github.com/astral-sh/uv) - 现代 Python 包管理器
- [FastMCP](https://github.com/jlowin/fastmcp) - 快速构建 MCP 服务器的框架

## 📊 版本历史

- **v0.1.2** - 当前版本
  - 完整的 MCP 工具集成
  - PRP 文档系统
  - 思维处理工具
  - 使用记录追踪
  - Java 快速编码工具
  - 技能专家系统

---

如果你觉得这个项目有用，请给它一个 ⭐️！