# MCP Chat

`mcp_starter_project` is a command-line chat application built around a local MCP server. The project supports two usage modes:

- **Anthropic Claude mode** using `main.py`
- **Google Gemini / GenAI mode** using `genai_main.py`

Both modes share the same MCP server implementation and document tooling in `mcp_server.py`, but use different model adapters and entrypoints.

## Runtime modes

| Mode | Entry point | Model adapter | Required env vars | Notes |
| --- | --- | --- | --- | --- |
| Claude | `main.py` | `core/claude.py` | `ANTHROPIC_API_KEY`, `CLAUDE_MODEL` | Uses Anthropic Claude and the Claude CLI flow |
| Gemini / GenAI | `genai_main.py` | `core/gemini.py` | `GOOGLE_API_KEY`, `GEMINI_MODEL` | Uses Google Gemini and the GenAI CLI flow |

## Prerequisites

- Python 3.10+
- Either Anthropic or Google Gemini credentials
- Optional: `uv` if you want to run the MCP server with `uv run`

## Setup

### 1. Configure environment variables

Create a `.env` file in the project root with the values for the mode you want to use.

#### Claude mode

```bash
ANTHROPIC_API_KEY="your_api_key_here"
CLAUDE_MODEL="claude-3.5-mini"
```

#### Gemini / GenAI mode

```bash
GOOGLE_API_KEY="your_google_api_key"
GEMINI_MODEL="gemini-3.1-flash-lite"
```

Optionally set `USE_UV=1` if you want `main.py` to launch `mcp_server.py` through `uv run` instead of the current Python interpreter.

### 2. Install dependencies

Use the provided `pyproject.toml` dependencies.

Recommended:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

If you do not want to install editable mode:

```bash
pip install anthropic python-dotenv prompt-toolkit "mcp[cli]>=1.8.0"
```

## Running the application

Choose one of the two supported runtime modes.

### Claude mode

```bash
python main.py
```

If you set `USE_UV=1`, `main.py` will start `mcp_server.py` through `uv run`.

You can also pass additional MCP server scripts to `main.py`:

```bash
python main.py another_server.py
```

### Gemini / GenAI mode

```bash
python genai_main.py
```

This path uses the Google Gemini adapter and the GenAI-specific CLI.

## How it works

- `main.py` starts the CLI app and launches `mcp_server.py` as a local MCP server.
- `mcp_client.py` manages the MCP session and exposes methods for listing tools, prompts, and reading resources.
- `mcp_server.py` defines documents, MCP tools, resources, and a prompt that can be executed through the MCP protocol.
- `core/cli.py` provides the interactive prompt with `/` command completion and `@` document ID completion.

## Usage

### Basic chat

Type a question and press Enter.

### Reference documents

Use `@<document_id>` to include a document into your query.
For example:

```bash
> Tell me about @deposition.md
```

The CLI will fetch the referenced document content from the MCP server and include it in the model prompt.

### Commands

Use `/` followed by a prompt name to run a server-side prompt.
For example, if the MCP server defines a prompt named `format`, type:

```bash
> /format deposition.md
```

Tab completion is available for prompt names and document IDs.

## Project structure

- `main.py` - application entry point for Anthropic Claude usage
- `mcp_client.py` - MCP client session wrapper for Claude mode
- `genai_main.py` - application entry point for Google Gemini / GenAI usage
- `genai_mcp_client.py` - MCP client session wrapper for GenAI mode
- `mcp_server.py` - local MCP server with documents, tools, and resources shared by both modes
- `core/cli.py` - prompt UI with completions and key bindings for Claude mode
- `core/cli_chat.py` - chat flow, document injection, and MCP prompts for Claude mode
- `core/chat.py` - general chat orchestration and model invocation for Claude mode
- `core/claude.py` - Anthropic Claude client wrapper
- `core/gemini.py` - Gemini model adapter for the GenAI flow
- `core/genai_cli.py` - CLI prompt UI with completions for GenAI mode
- `core/genai_cli_chat.py` - GenAI CLI chat flow with MCP-backed resources
- `core/genai_chat.py` - GenAI chat orchestration and tool loop handling

## Development notes

- Add or update documents in the `docs` dictionary inside `mcp_server.py`.
- Add new MCP prompts and tools in `mcp_server.py` to extend the CLI capabilities.
- `mcp_client.py` already includes MCP session helpers; you can expand it to expose more server operations.