Startup MVP — MCP Server & Client

This repository implements the project structure requested in the exercise: a small MCP-style tools server and a CLI client that can call the server's tools. The implementation is intentionally minimal and deterministic so it runs without external API keys, while also allowing integration with real APIs when the corresponding environment variables are provided.

Key features included:

• MCP tools server (server/mcp_server.py) exposing endpoints for currency conversion, geocoding and weather.

• Client CLI (client/cli_interface.py) that supports English commands and Spanish special commands requested in the exercise (/salir, /clear, /status, /help).

• Clear, documented project layout with environment example and requirements.

Architecture

• Server: FastAPI app in server/mcp_server.py providing lightweight tools endpoints.

• Client: Python CLI in client/cli_interface.py that calls the MCP server using HTTP.

• Config: config/settings.py centralizes env-based settings.

Related MCP server: Weather MCP Server

Files and structure

startup-mvp/
├── server/
│   ├── __init__.py
│   ├── mcp_server.py           # FastAPI app exposing tools
│   ├── currency_tools.py       # Currency conversion helpers
│   ├── weather_tools.py        # Weather helper (requires coords)
│   ├── geocoding_tools.py      # City -> coordinates helper
│   └── api_clients.py          # HTTP clients for external APIs
├── client/
│   ├── __init__.py
│   ├── openai_client.py        # Client helpers that talk to the MCP server
│   └── cli_interface.py        # CLI with Spanish special commands (/salir, /clear, /status)
├── config/
│   ├── __init__.py
│   └── settings.py             # Environment-driven settings
├── main_server.py              # Run the MCP server (uvicorn)
├── main_client.py              # Run the CLI (asyncio)
├── requirements.txt
├── .env.example                # Example env vars
└── README.md

Endpoints (MCP server)

• POST /tools/convert_currency - body: { "amount": float, "src": "USD", "dst": "EUR" }

• POST /tools/geocode - body: { "city": "Madrid" }

• POST /tools/weather - body: { "lat": float, "lon": float }

Added chat endpoints:

• POST /chat/message - body: { "user_message": "..." } — returns saved message and deterministic assistant reply.

• GET /chat/history - returns saved chat history.

• DELETE /chat/history - clears chat history.

Web UI:

The repository now includes a minimal web UI under ui/. When the MCP server is running you can open:

http://127.0.0.1:8000/ui/index.html

to interact with the /chat endpoints from the browser.

The server returns deterministic placeholder data when external API keys are not set.

Entrega (versión final)

The final, cleaned project ready for delivery is located in the entrega/ folder at the repository root. It contains only the files required by the exercise and a minimal CI workflow under entrega/.github/workflows/ci.yml.

All other auxiliary files, tests, Docker artifacts and scripts were moved to archivos_extras/.

CLI usage (important: supports Spanish special commands)

Start the server in one terminal:

python main_server.py

Start the client in another terminal:

python main_client.py

Commands you can use inside the CLI:

• convert <amount> <src> <dst> — Convert currencies (e.g. convert 10 USD EUR).

• geocode <city> — Get coordinates for a city (e.g. geocode Madrid).

• weather <lat> <lon> — Get weather for coordinates (e.g. weather 40.41 -3.7).

Spanish special commands (as requested in the exercise):

• /salir — Salir del CLI (equivalent to exit).

• /clear — Limpiar historial local (if present). Note: the MCP tools server does not persist chat history by default.

• /status — Comprueba la disponibilidad del servidor MCP (intenta acceder a /openapi.json).

• /help — Mostrar esta ayuda.

All commands also accept English equivalents for exit/quit.

Running and testing

1. Create and activate a virtualenv and install dependencies:

python -m venv venv
venv\Scripts\activate   # Windows
pip install -r requirements.txt

2. Launch the server and client as shown above, then try examples:

$ convert 10 USD EUR
$ geocode Barcelona
$ weather 41.3851 2.1734
$ /status
$ /salir