Project Overview

Project Purpose and Objectives

This project implements a Zoo Animal MCP (Model-Controller-Processor) server to provide an extensible API for querying zoo animal data via asynchronous services. The core goal is to create a lightweight, scalable backend service deployed on Google Cloud Run, exposing tools to retrieve animal information by species or name.

Key objectives include:

• Building an asynchronous MCP server using the FastMCP framework.

• Providing two primary query tools:

  • Retrieve lists of animals filtered by species.

  • Retrieve detailed information for a specific animal by name.

• Enabling flexible deployment on Google Cloud Run with both secure and unauthenticated modes.

• Simplifying cloud deployment and environment configuration through standardized shell scripts.

• Ensuring reproducible environments via Python dependency locking.

Functionally, the system maintains a structured in-memory dataset of zoo animals with attributes such as species, name, age, enclosure, and trail. The MCP server exposes this data through decorated tools accessible via HTTP endpoints. The server listens on a configurable port and handles concurrent requests asynchronously.

Example Workflows and Use Cases

Example: Query Animals by Species

1. A client sends a request with a species identifier (e.g., "giraffe").

2. The MCP server's get_animals_by_species tool filters the internal animal list to return all matching entries.

3. The response is a JSON list of animal objects containing species, name, age, enclosure, and trail details.

Example: Retrieve Animal Details by Name

1. A client requests detailed information about a specific animal by name (e.g., "Melman").

2. The get_animal_details tool searches the animal list for a matching name.

3. If found, it returns a detailed dictionary about that animal; if not found, it returns an empty dictionary.

Deployment Workflow

• Run init.sh to configure GCP project, enable required APIs, and set IAM roles.

• Source set_env.sh to load environment variables.

• Use cloudrun.sh or cloudrun-secure.sh to deploy the MCP server to Cloud Run with unauthenticated or authenticated access respectively.

• Retrieve logs via getlogs.sh for operational monitoring.

Stack and Technologies

• Python 3 with asynchronous programming (asyncio): chosen for concurrency and ease of writing async HTTP services.

• FastMCP framework: provides MCP server abstraction and tool decorators to build modular, extensible endpoints.

• Google Cloud Run: serverless container platform for scalable deployment with minimal infrastructure management.

• Google Cloud CLI (gcloud): used extensively in shell scripts for project configuration, authentication, deployment, and monitoring.

• Shell scripting (bash): automates environment setup, deployment, and log retrieval.

• Poetry / Python dependency management: ensures reproducible Python environments via uv.lock and pyproject.toml.

• Logging: Python’s standard logging module for server-side event tracking.

These technologies collectively enable a cloud-native, containerized, and asynchronous service designed for efficient deployment and operational simplicity.

High-Level Architecture

The architecture consists of the following main components:

• Frontend / Client: External callers or applications that send HTTP requests to the MCP server to query zoo animal information.

• Zoo Animal MCP Server (server.py): The core asynchronous Python service exposing tools to query animals by species or name. It uses FastMCP for tool registration and HTTP serving.

• Google Cloud Run: Hosts the MCP server as a containerized, managed service. Two deployment modes exist:

  • Unauthenticated (cloudrun.sh): Publicly accessible.

  • Secure (cloudrun-secure.sh): Requires identity tokens for access.

• Google Cloud Project and IAM: Manages authentication, authorization, and resource permissions configured via init.sh and environment variables set in set_env.sh.

• Logging and Monitoring: Logs collected from Cloud Run instances accessible via getlogs.sh.

Communication flow:

• Clients send requests → Cloud Run MCP server handles asynchronously → MCP tools query in-memory data → Results returned to clients.

graph TB
Client -->|HTTP Requests| MCP_Server[Zoo Animal MCP Server]
MCP_Server --> InMemoryData[Zoo Animal Dataset]
MCP_Server -->|Runs on| CloudRun[Google Cloud Run]
CloudRun -->|Logs| Logging[Cloud Logging]
InitScripts[init.sh, set_env.sh] --> CloudRun
DeployScripts[cloudrun.sh, cloudrun-secure.sh] --> CloudRun

Developer Navigation

Frontend Developers Start Here

• Interact with the MCP server via HTTP requests.

• Review server.py to understand available tools and response formats.

• Use the documented tool names: get_animals_by_species, get_animal_details.

• Test endpoints locally or against deployed services.

Backend Developers Focus Here

• Modify or extend zoo animal data and tool logic in server.py.

• Add new MCP tools using the @mcp.tool decorator.

• Leverage asynchronous patterns using asyncio.

• Manage dependencies via pyproject.toml and uv.lock.

• Update logging configuration as needed.

DevOps / Deployment Focus

• Use init.sh to initialize Google Cloud project settings and permissions.

• Source set_env.sh to set environment variables for deployment.

• Deploy with cloudrun.sh (public) or cloudrun-secure.sh (authenticated).

• Retrieve service logs using getlogs.sh.

• Review and update the Dockerfile for container image customization.

Visual Diagrams

Component Diagram: High-Level Architecture

graph TB
Client --> MCP[Zoo Animal MCP Server]
MCP --> Data[In-Memory Zoo Dataset]
MCP --> CloudRun[Google Cloud Run]
CloudRun --> Logs[Cloud Logging]
Init[Init & Env Scripts] --> CloudRun
Deploy[Deploy Scripts] --> CloudRun

Flowchart: Query Animal Details Workflow

flowchart TD
A[Client Request: Animal Name] --> B{Is Name in Dataset?}
B -- Yes --> C[Return Animal Details]
B -- No --> D[Return Empty Response]
C --> E[Send Response to Client]
D --> E

This overview provides a clear technical roadmap for developers to understand the project components, workflows, and how to contribute effectively.