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这个命令将会：
- 抓取Asaas的文档数据
- 为每一页生成嵌入向量
- 创建FAISS索引
- 保存所有内容到
data/
2. 启动服务器
标准I/O模式（MCP）
要与MCP客户端（如Claude Desktop）一起使用：
npm run start:stdioREST 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🤝 贡献/助力
欢迎贡献！请随意：
- 为项目创建分支（或分叉）
- 为你的功能创建一个分支
git checkout -b feature/MinhaFeature) - 提交你的更改
git commit -m 'Adiciona MinhaFeature') - 推送到分支（
git push origin feature/MinhaFeature) - 提交一个拉取请求（Pull Request）
📝 许可证
ISC（国际安全认证/信息安全体系等，具体含义根据上下文而定）
🔗 链接
💡 下一步行动
- \[ \] 添加更多文献来源
- \[ \] 实现嵌入缓存
- \[ \] 添加自动化测试
- \[ \] 创建用于搜索的网页界面
- \[ \] 支持多种语言
- \[ \] 文档自动更新
______________________________________________________________________
用心打造，献给开发者社区