donnersyt/mcp-abbreviations

MCP Abbreviations Server

This project implements a FastAPI server to manage and search for abbreviations, with a focus on integrating with Google Cloud services like Firestore and Vertex AI for semantic search capabilities. The server exposes its functionality through a standard REST API and also via the Model Context Protocol (MCP), allowing it to be used as a tool by other services like Gemini.

Features

• Abbreviation Lookup: Search for abbreviations by their exact name.
• Semantic Search: Search for abbreviations based on the meaning of their definitions using Gemini embeddings.
• Firestore Integration: Stores and retrieves abbreviation data from a Google Cloud Firestore database.
• FastAPI and MCP: Built with FastAPI for a robust and fast API, and uses FastMCP to expose the server's functionality as a tool.
• Asynchronous: Utilizes async/await for non-blocking I/O operations.

Technologies Used

• Python 3.13+
• FastAPI: A modern, fast (high-performance) web framework for building APIs with Python.
• FastMCP: A library for creating MCP tools with FastAPI.
• Google Cloud Firestore: A NoSQL document database built for automatic scaling, high performance, and ease of application development.
• Google Cloud Vertex AI: Used for generating embeddings for semantic search with the Gemini family of models.
• Pydantic: Data validation and settings management using Python type annotations.
• uv: A fast Python package installer and resolver.

Setup and Installation

Prerequisites

• Python 3.13 or higher.
• A Google Cloud Platform (GCP) project with the following APIs enabled:
  • Firestore API
  • Vertex AI API
• The gcloud command-line tool installed and configured on your local machine.

1. Clone the Repository

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

2. Create a Virtual Environment

It is recommended to use a virtual environment to manage the project's dependencies.

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

3. Install Dependencies

This project uses uv to manage dependencies. The dependencies are listed in the pyproject.toml file.

pip install uv
uv pip install -r requirements.txt

4. Configure GCP Authentication

You need to authenticate with your GCP account to use the Firestore and Vertex AI services.

gcloud auth application-default login

5. Seed the Firestore Database

Before running the server, you need to populate the Firestore database with the abbreviation data from the data/abbreviations.json file.

First, you need to update the PROJECT_ID in the seed_firestore.py file with your GCP project ID.

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

Then, run the script to seed the database:

python seed_firestore.py

Running the Server

To start the FastAPI server, run the following command:

uvicorn main:app --reload

The server will be available at http://localhost:8000.

API Endpoints

The server exposes the following endpoints:

• GET /: A simple endpoint to check if the server is running.
• GET /health: A health check endpoint that verifies the connection to Firestore and the availability of the embedding model.
• POST /mcp-server/mcp: The MCP endpoint for interacting with the server's tools.

The following tools are available through the MCP endpoint:

• search_abbreviations: Searches for an abbreviation by its exact name.
  • Input: {"query": "GCP"}
  • Output: {"results": [{"abbreviation": "GCP", "definition": "...", "source": "...", "status": "..."}]}
• search_by_definition: Performs a semantic search on the definitions of the abbreviations.
  • Input: {"query": "cloud storage service"}
  • Output: {"results": [{"abbreviation": "...", "definition": "...", "source": "...", "status": "...", "similarity_score": 0.85}]}

You can also access the FastAPI documentation at http://localhost:8000/docs for more details on the API.

Project Structure

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