AI导哈

缩写查询服务

一个基于FastAPI的缩写管理和搜索服务，集成Google Cloud Firestore和Vertex AI，支持精确查询和语义搜索。

  • by donneeers
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 donnersyt/mcp-abbreviations

使用说明

MCP缩写服务器

该项目实现了一个FastAPI服务器来管理和搜索缩写，重点是与Firestore和Vertex AI等谷歌云服务集成，以实现语义搜索功能。服务器通过标准的REST API和模型上下文协议（MCP）公开其功能，从而允许Gemini等其他服务将其用作工具。

特性

  • 缩写查找： 按缩写的确切名称搜索缩写。
  • 语义搜索： 使用Gemini嵌入根据其定义的含义搜索缩写。
  • Firestore集成： 从Google Cloud Firestore数据库中存储和检索缩写数据。
  • FastAPI和MCP： 使用FastAPI构建健壮快速的API，并使用FastMCP将服务器的功能作为工具公开。
  • 异步： 将async/await用于非阻塞I/O操作。

使用的技术

  • Python 3.13+
  • FastAPI： 一个现代、快速（高性能）的web框架，用于使用Python构建API。
  • FastMCP： 使用FastAPI创建MCP工具的库。
  • 谷歌云火商店： 一个为自动扩展、高性能和易于应用程序开发而构建的NoSQL文档数据库。
  • 谷歌云顶点AI： 用于生成Gemini系列模型的语义搜索嵌入。
  • Pydantic： 使用Python类型注释进行数据验证和设置管理。
  • 紫外线： 一个快速的Python包安装程序和解析器。

设置和安装

先决条件

  • Python 3.13或更高版本。
  • 启用了以下API的Google Cloud Platform（GCP）项目：
    • Firestore API
    • Vertex AI API
  • 这 gcloud 命令行工具已安装并配置在本地计算机上。

1.克隆存储库

git clone https://github.com/your-username/mcp-abbreviations-server.git
cd mcp-abbreviations-server

2.创建虚拟环境

建议使用虚拟环境来管理项目的依赖关系。

python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`

3.安装依赖项

此项目使用 uv 管理依赖关系。依赖关系列在 pyproject.toml 文件。

pip install uv
uv pip install -r requirements.txt

4.配置GCP身份验证

您需要使用您的GCP帐户进行身份验证才能使用Firestore和Vertex AI服务。

gcloud auth application-default login

5.为Firestore数据库添加种子

在运行服务器之前，您需要使用来自的缩写数据填充Firestore数据库 data/abbreviations.json 文件。

首先，您需要更新 PROJECT_ID 在 seed_firestore.py 使用您的GCP项目ID创建文件。

# seed_firestore.py
PROJECT_ID = "your-gcp-project-id"

然后，运行脚本为数据库添加种子：

python seed_firestore.py

运行服务器

要启动FastAPI服务器，请运行以下命令：

uvicorn main:app --reload

服务器将在以下时间可用 http://localhost:8000.

API终点

服务器公开以下端点：

  • GET /：一个简单的端点，用于检查服务器是否正在运行。
  • GET /health：一个健康检查端点，用于验证与Firestore的连接以及嵌入模型的可用性。
  • POST /mcp-server/mcp：用于与服务器工具交互的MCP端点。

以下工具可通过MCP端点使用：

  • search_abbreviations：按缩写的确切名称搜索缩写。
    • 输入： {"query": "GCP"}
    • 输出： {"results": [{"abbreviation": "GCP", "definition": "...", "source": "...", "status": "..."}]}
  • search_by_definition：对缩写的定义执行语义搜索。
    • 输入： {"query": "cloud storage service"}
    • 输出： {"results": [{"abbreviation": "...", "definition": "...", "source": "...", "status": "...", "similarity_score": 0.85}]}

您还可以访问FastAPI文档，网址为 http://localhost:8000/docs 了解有关API的更多详细信息。

项目结构

.
├── data/
│   └── abbreviations.json  # The source data for the abbreviations
├── main.py                 # The main FastAPI application
├── seed_firestore.py       # Script to seed the Firestore database
├── pyproject.toml          # Project metadata and dependencies
├── requirements.txt        # List of dependencies for uv
├── README.md               # This file
└── ...

相关 MCP