# Ace-MCP-Go

> Go 语言实现的 Model Context Protocol (MCP) 服务器，为 AI 助手提供代码库索引和语义搜索能力

[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[English](README_EN.md) | 简体中文

## 📖 简介

**Ace-MCP-Go** 是一个使用 Go 语言实现的 MCP 服务器，旨在为 AI 助手（如 Claude、GPT、Cursor 等）提供强大的代码库索引和语义搜索功能。

### 核心特性

- **🚀 高性能**: 利用 Go 的并发特性，支持大规模代码库的快速索引
- **🔍 语义搜索**: 基于外部 API 的智能代码检索
- **📦 增量索引**: SHA-256 哈希去重，只处理变更文件
- **🌐 跨平台**: 完整支持 Windows、Linux、macOS 和 WSL
- **🎯 零配置**: 首次运行自动生成默认配置
- **🖥️ Web 管理**: 实时日志、项目管理、配置编辑

## 🎯 使用场景

- AI 辅助代码审查和理解
- Bug 调试和问题定位
- 快速理解大型代码库
- 代码重构辅助
- 自动化文档生成

## 🏗️ 架构设计

```
MCP 客户端 (Claude/Cursor)
    ↕ stdio (JSON-RPC)
MCP 服务器层
    ↕
业务逻辑层 (IndexManager)
    ↕ 并发处理
文件收集 → 哈希计算 → 批量上传
    ↕
外部 API + 本地数据库
```

### 并发模型

- **文件收集**: Worker Pool 模式，并发度 = CPU 核数 × 2
- **哈希计算**: 并发处理，并发度 = CPU 核数
- **批量上传**: Semaphore 限流，最大 3 并发请求

## 🚀 快速开始

### 前置要求

- Go 1.21 或更高版本
- Git

### 安装

```bash
# 克隆仓库
git clone https://github.com/yourusername/ace-mcp-go.git
cd ace-mcp-go

# 安装依赖
make install

# 构建
make build
```

### 配置

首次运行会自动生成配置文件 `~/.acemcp/settings.toml`：

```toml
[api]
endpoint = "https://api.example.com"
token = "your-api-token-here"

[index]
batch_size = 10
max_lines = 800
concurrency = 0  # 0 = 自动检测

[web_server]
enabled = true
host = "127.0.0.1"
port = 3000
```

编辑配置文件，设置您的 API 端点和令牌。

### 运行

```bash
# MCP 服务器模式（stdio）
./bin/acemcp

# 带 Web 管理界面
./bin/acemcp --web-server
```

### 与 Claude Desktop 集成

编辑 Claude Desktop 配置文件：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "acemcp-go": {
      "command": "/path/to/ace-mcp-go/bin/acemcp"
    }
  }
}
```

重启 Claude Desktop 即可使用 `search_context` 工具。

## 📚 开发文档

详细的开发文档请参阅 [DEVELOPMENT.md](DEVELOPMENT.md)。

### 项目结构

```
ace-mcp-go/
├── cmd/acemcp/              # 主程序入口
├── internal/                # 私有代码
│   ├── config/             # 配置管理
│   ├── logger/             # 日志系统
│   ├── errors/             # 错误处理
│   ├── index/              # 索引管理
│   ├── tools/              # MCP 工具
│   ├── web/                # Web 服务器
│   └── utils/              # 工具函数
├── pkg/apiclient/          # API 客户端
└── configs/                # 配置示例
```

### 开发命令

```bash
# 运行测试
make test

# 运行测试并生成覆盖率报告
make test-coverage

# 运行性能测试
make bench

# 格式化代码
make fmt

# 开发模式（热重载）
make dev

# 多平台构建
make build-all
```

## 🧪 测试

```bash
# 运行所有测试
make test

# 查看覆盖率
make test-coverage
# 在浏览器中打开 coverage.html

# 性能测试
make bench
```

## 📦 构建

```bash
# 本地构建
make build

# 多平台构建
make build-all
# 生成文件：
# - bin/acemcp-windows-amd64.exe
# - bin/acemcp-linux-amd64
# - bin/acemcp-darwin-amd64
# - bin/acemcp-darwin-arm64
```

## 🛠️ 技术栈

| 模块 | 技术 | 说明 |
|------|------|------|
| MCP SDK | `modelcontextprotocol/go-sdk` | 官方 SDK |
| Web 框架 | `gin-gonic/gin` | 高性能 HTTP 框架 |
| 日志 | `sirupsen/logrus` | 结构化日志 |
| 配置 | `spf13/viper` | 配置管理 |
| HTTP 客户端 | `go-resty/resty` | REST 客户端 |
| WebSocket | `gorilla/websocket` | WebSocket 支持 |
| 并发控制 | `golang.org/x/sync` | 官方并发库 |

## 🤝 贡献

欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。

### 开发流程

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

## 📝 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 📧 联系方式

- Issue: [GitHub Issues](https://github.com/xiaoxu123195/ace-mcp-go/issues)
- Email: cherrytump@gmail.com

## 🌟 致谢

感谢所有贡献者和 MCP 社区的支持！

---

**注意**: 本项目目前处于活跃开发阶段，API 可能会有变更。