# Contact Book MCP Server

A simple [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that manages an in-memory contact book. Built with `FastMCP` from the `mcp` Python SDK.

## Features

This server exposes four tools:

| Tool | Description |
|------|-------------|
| `add_contact(name, phone, email)` | Adds a new contact to the contact book. |
| `get_contact(name)` | Retrieves a contact by exact name match. |
| `search_contacts(query)` | Searches contacts by partial (case-insensitive) name match. |
| `update_contact(name, phone, email)` | Updates an existing contact's phone and email. |

Contacts are stored in memory as:

```python
contacts: dict[str, dict]  # name -> {"phone": ..., "email": ...}
```

> **Note:** Data is stored in memory only. All contacts are lost when the server restarts.

## Requirements

- Python 3.10+
- [`uv`](https://docs.astral.sh/uv/) (recommended for running the server)

## Installation

1. Clone this repository:
   ```bash
   git clone <your-repo-url>
   cd contact_book_server_mcp
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
   Or, if using `uv` (recommended, no manual install needed — see below).

## Running the Server

### With MCP Inspector (for testing/development)

```bash
uv run --with mcp mcp dev server.py
```

This starts the server and opens the MCP Inspector in your browser, where you can test each tool interactively.

### Standalone

```bash
python server.py
```

## Example Usage

1. **Add a contact**
   ```
   add_contact(name="Humna Fahad", phone="03001234567", email="humna@test.com")
   → "Contact 'Humna Fahad' added successfully."
   ```

2. **Get a contact**
   ```
   get_contact(name="Humna Fahad")
   → {"name": "Humna Fahad", "phone": "03001234567", "email": "humna@test.com"}
   ```

3. **Search contacts**
   ```
   search_contacts(query="Hum")
   → [{"name": "Humna Fahad", "phone": "03001234567", "email": "humna@test.com"}]
   ```

4. **Update a contact**
   ```
   update_contact(name="Humna Fahad", phone="03009998888", email="humna@updated.com")
   → "Contact 'Humna Fahad' updated successfully."
   ```

## Project Status

✅ All four tools implemented and tested via MCP Inspector.

## Possible Improvements

- Add a `delete_contact` tool.
- Add a `list_all_contacts` tool.
- Persist contacts to a JSON file or database instead of in-memory storage.