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
└── ...