MCP Asaas Server

MCP 服务器 Asaas 🚀

用于Asaas API文档的MCP（模型上下文协议）服务器，支持使用FAISS进行语义搜索。

📋 特点

• ✅ 语义搜索使用嵌入和FAISS在文档中进行智能搜索
• ✅ 双接口同时支持stdio（MCP）和REST API
• ✅ 结构化模式使用优化后的JSON Schema组织的数据
• ✅ 自动抓取自动收集官方文件
• ✅ 向量索引使用FAISS进行快速索引以实现高效搜索

🛠️ 技术

• Node.js - 运行时JavaScript
• @modelcontextprotocol/sdk 翻译为中文是：“@模型上下文协议/开发工具包”。不过，这里的“@modelcontextprotocol”可能是一个特定项目或框架的名称，直接翻译可能无法准确传达其原意，因此在实际应用中，可能需要根据具体上下文来确定更准确的翻译。但基于直译，上述翻译是一个基本的表达 - MCP的SDK（软件开发工具包）
• FAISS（高效相似性搜索库） 高性能向量搜索
• OpenAI（开放人工智能研究所） - 生成嵌入表示
• 快递 - REST服务器
• 再见（Cheerio是苏格兰英语中的告别语，相当于中文的“再见”） - 网络爬虫（或网页数据抓取）
• Axios（注：Axios是一个用于浏览器和Node.js的基于promise的HTTP客户端） - HTTP客户端

📦 安装

# Clone o repositório
git clone https://github.com/suissa/mcp-asaas-server.git
cd mcp-asaas-server

# Instale as dependências
npm install

# Configure as variáveis de ambiente
cp .env.example .env
# Edite .env e adicione sua OPENAI_API_KEY

⚙️ 设置

创建一个文件 .env 项目根源：

OPENAI_API_KEY=sk-your-api-key-here
PORT=3000

🚀 使用

1. 文档索引化

首先，你需要收集并索引文档：

npm run index

这个命令将会：

1. 抓取Asaas的文档数据
2. 为每一页生成嵌入向量
3. 创建FAISS索引
4. 保存所有内容到 data/

2. 启动服务器

标准I/O模式（MCP）

要与MCP客户端（如Claude Desktop）一起使用：

npm run start:stdio

REST API 模式

要作为REST API使用：

npm run start:rest
# ou simplesmente
npm start

服务器将在 http://localhost:3000

📚 API REST

可用的终端点

GET /

API文档

GET /health

健康检查和基本统计

{
  "status": "ok",
  "timestamp": "2025-01-10T12:00:00.000Z",
  "stats": {
    "totalDocuments": 11,
    "dimension": 1536,
    "indexInitialized": true
  }
}

POST /search

在文档中进行语义搜索

主体/身体：

{
  "query": "como criar um cliente",
  "limit": 5
}

回答：

{
  "query": "como criar um cliente",
  "total": 5,
  "results": [
    {
      "document": {
        "id": "aHR0cHM6Ly9kb2Nz",
        "title": "Criar Cliente",
        "url": "https://docs.asaas.com/reference/clientes",
        "method": "POST",
        "endpoint": "/v3/customers",
        "description": "Endpoint para criar novos clientes...",
        "category": "clientes",
        "tags": ["cliente", "criar", "api"]
      },
      "score": 0.1234
    }
  ]
}

GET /documents

列出所有文件

查询参数：

• limit （默认：50）- 每页文档数量
• offset （默认：0）- 分页偏移量

GET /documents/:id

按ID搜索特定文档

GET /categories

列出所有可用的类别

GET /categories/:category

搜索特定类别的文件

GET /tags

列出所有可用的标签

GET /tags/:tag

搜索带有特定标签的文档

GET /stats

返回知识库的详细统计数据

🔧 使用MCP（stdio）

在Claude桌面版中的设置

添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "asaas-docs": {
      "command": "node",
      "args": [
        "/caminho/para/mcp-asaas-server/src/mcp/stdio-server.js"
      ],
      "env": {
        "OPENAI_API_KEY": "sua-chave-aqui"
      }
    }
  }
}

可用工具

search_asaas_docs

在文档中进行语义搜索

参数：

• query （必填）：自然语言查询
• limit （可选）：结果数量（默认：5）

get_asaas_stats

返回知识库统计信息

list_asaas_categories

列出所有可用的类别

📊 数据架构

知识库中的每个文档都遵循以下模式：

{
  id: string;              // ID único
  title: string;           // Título da página
  content: string;         // Conteúdo completo
  url: string;             // URL original
  category?: string;       // Categoria (ex: "clientes")
  method?: "GET"|"POST"|"PUT"|"DELETE"|"PATCH";
  endpoint?: string;       // Path do endpoint
  description?: string;    // Descrição curta
  parameters?: Array;
  examples?: Array;
  tags?: string[];         // Tags para categorização
}

🔍 使用示例

REST API（Representational State Transfer Application Programming Interface，表述性状态传递应用程序编程接口）

# Buscar informações sobre clientes
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "como criar um cliente", "limit": 3}'

# Listar categorias
curl http://localhost:3000/categories

# Buscar por categoria
curl http://localhost:3000/categories/clientes

# Ver estatísticas
curl http://localhost:3000/stats

用JavaScript

// Busca semântica
const response = await fetch('http://localhost:3000/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'como criar uma cobrança',
    limit: 5
  })
});

const data = await response.json();
console.log(data.results);

📁 项目结构

mcp-asaas-server/
├── src/
│   ├── schemas/
│   │   └── documentation.schema.json    # JSON Schema dos dados
│   ├── scraper/
│   │   └── asaas-scraper.js            # Scraper da documentação
│   ├── vectorstore/
│   │   └── faiss-store.js              # Gerenciador do índice FAISS
│   └── mcp/
│       ├── stdio-server.js             # Servidor MCP (stdio)
│       └── rest-server.js              # Servidor REST
├── scripts/
│   └── index-docs.js                   # Script de indexação
├── data/
│   ├── asaas-docs.json                 # Dados brutos
│   └── faiss/
│       ├── index.faiss                 # Índice FAISS
│       └── documents.json              # Documentos indexados
├── package.json
├── .env.example
└── README.md

🤝 贡献/助力

欢迎贡献！请随意：

1. 为项目创建分支（或分叉）
2. 为你的功能创建一个分支git checkout -b feature/MinhaFeature)
3. 提交你的更改git commit -m 'Adiciona MinhaFeature')
4. 推送到分支（git push origin feature/MinhaFeature)
5. 提交一个拉取请求（Pull Request）

📝 许可证

ISC（国际安全认证/信息安全体系等，具体含义根据上下文而定）

🔗 链接

• 官方文档 Asaas
• 模型上下文协议
• FAISS（高效相似性搜索库）

💡 下一步行动

• \[ \] 添加更多文献来源
• \[ \] 实现嵌入缓存
• \[ \] 添加自动化测试
• \[ \] 创建用于搜索的网页界面
• \[ \] 支持多种语言
• \[ \] 文档自动更新

______________________________________________________________________

用心打造，献给开发者社区