# MCP User CRUD Server

A small test server that speaks **MCP (Model Context Protocol)**. MCP is a standard way for AI assistants (like Claude) to call tools and get real data back, instead of just guessing answers.

This server manages a simple list of users (name, email, phone, age) stored in a plain JSON file. It's meant for **testing and learning**, not for storing real/production data.

## What it can do

The server gives an AI assistant 5 tools it can call:

| Tool | What it does |
|---|---|
| `list_users` | Show every user |
| `search_user` | Find users by any field (name, email, phone, age, id) |
| `add_user` | Create a new user |
| `update_user` | Change one or more fields on an existing user |
| `delete_user` | Remove a user |

All the data lives in `users_db.json`, right next to the server script. You can open that file in any text editor to see or edit it directly.

## Before you start

You need **Python 3.10 or newer** installed on your computer.

- Windows: download it from [python.org](https://www.python.org/downloads/)
- Mac: run `brew install python3` (or download from python.org)
- Linux: usually already installed; if not, `sudo apt install python3 python3-venv` (Ubuntu/Debian) or your distro's equivalent

You do **not** need to install anything else by hand — the launcher scripts below do that for you automatically the first time you run them.

## How to run it

Pick the file that matches your computer. Everything else (installing dependencies, etc.) happens automatically.

- **Windows** → double-click `run_server.bat`
- **Mac** → double-click `run_server_mac.command`
  (if macOS blocks it the first time, right-click the file → *Open* → confirm)
- **Linux** → open a terminal in this folder and run `bash run_server_linux.sh`

The first time you run it, it may take a minute to set itself up. After that it starts instantly.

## Choosing authentication

Every time you start the server, it asks how you want to protect it:

```
1. None         (no authentication)
2. API Key      (client sends X-API-Key header)
3. Bearer Token (client sends Authorization: Bearer <token> header)
```

- **None** — anyone who can reach the server can use it. Good for a quick local test.
- **API Key** — the server makes up a secret key (or you can type your own), and only requests that include that exact key are allowed in.
- **Bearer Token** — same idea as API Key, just using the `Authorization: Bearer ...` header style that a lot of tools expect.

Whichever you pick, the server prints the secret and a ready-to-use connection block right in the console — you don't need to remember or configure anything by hand.

## Connecting to it

When the server starts, it prints something like this:

```
This machine  : http://127.0.0.1:8765/mcp
LAN / remote  : http://192.168.1.42:8765/mcp
Auth mode     : api_key
Secret        : Xy82jKf...

Client config (Claude Desktop / Claude Code / Cursor, etc.):
{
  "mcpServers": {
    "test-user-db": {
      "type": "streamable-http",
      "url": "http://192.168.1.42:8765/mcp",
      "headers": { "X-API-Key": "Xy82jKf..." }
    }
  }
}
```

Copy that JSON block into whichever MCP-compatible app you're connecting from (Claude Desktop, Claude Code, Cursor, etc.), and it will be able to see and use the 5 tools listed above.

- Use the `127.0.0.1` URL if the app is on the **same computer** as the server.
- Use the `LAN / remote` URL if you're connecting from a **different computer** on the same network.

## Files in this folder

| File | Purpose |
|---|---|
| `start_server.py` | The actual server code |
| `users_db.json` | The user data (plain JSON, safe to edit by hand) |
| `run_server.bat` | One-click launcher for Windows |
| `run_server_mac.command` | One-click launcher for Mac |
| `run_server_linux.sh` | Launcher for Linux |
| `requirements.txt` | List of Python packages the server needs |
| `test_client.py` | A script to test the server automatically (optional, not required to use the server) |

## Good to know

- This is a **testing tool**, not a production system. There's no encryption of the data file, and the API key / bearer token are simple shared secrets, not full user accounts.
- Stopping the server: just close the console window, or press `Ctrl+C` inside it.
- To clear all data, delete everything inside `users_db.json` and replace it with `[]`. If the file is missing entirely, the server just starts with zero users and creates the file again as soon as you add one.