<h1 align="center">🗂️ Next-Generation MCP Server</h1>

<p align="center">
  A modular <b>FastMCP</b> file-operations server, a faithful <b>Claude</b> CLI client,
  and a <b>Groq-powered</b> ChatGPT-style web UI.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python 3.10+" />
  <img src="https://img.shields.io/badge/FastMCP-2.12-purple" alt="FastMCP" />
  <img src="https://img.shields.io/badge/UI-Chainlit-ff4b6e" alt="Chainlit" />
  <img src="https://img.shields.io/badge/MCP-STDIO-green" alt="MCP STDIO" />
</p>

A sandboxed file-operations **MCP server** that showcases the advanced `Context`
features — **logging**, **progress reporting**, and **user elicitation** — with
two ways to drive it: a **Claude CLI** (`client.py`) and a **Groq web chat** (`app.py`).

## Capabilities

**🛠️ Tools** (model-controlled — the agent calls them):

| Tool | Description |
|------|-------------|
| `write_file(file_path, content)` | Create/overwrite a file (with progress reporting) |
| `read_file(file_path)` | Read a file's content |
| `append_to_file(file_path, content)` | Append to a file |
| `delete_file(file_path)` | Delete a file |
| `move_file(source, destination)` | Move / rename |
| `copy_file(source, destination)` | Copy a file |
| `make_directory(dir_path)` | Create a directory |
| `search_files(query, extension)` | Search file contents across the project |
| `file_info(file_path)` | File/dir metadata |

**📄 Resources** (app-controlled): `file:///{file_name}` (read file) · `dir://.` (list dir) · `stats://project` (project statistics)

**💬 Prompts** (user-controlled): `code_review` · `documentation_generator` (elicitation) · `generate_tests` · `explain_code`

## Project structure

```
next-generation-mcp-server/
├── fileops/                # modular MCP server package
│   ├── config.py           # BASE_DIR, server name/instructions, ignore list
│   ├── paths.py            # get_path() path-traversal guard
│   ├── schemas.py          # Pydantic models (elicitation)
│   ├── server.py           # builds `mcp`, registers tools/resources/prompts
│   ├── tools.py            # @mcp.tool definitions
│   ├── resources.py        # @mcp.resource definitions
│   └── prompts.py          # @mcp.prompt definitions
├── server.py               # entry point  →  python server.py
├── client.py               # Claude CLI client (Anthropic)
├── app.py                  # Groq chat UI (Chainlit)
├── chainlit.md
├── tests/test_server.py    # smoke test of all capabilities
├── pyproject.toml · requirements.txt · .env.example · .gitignore · README.md
```

## Setup

```bash
cd next-generation-mcp-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1        # Windows  (macOS/Linux: source .venv/bin/activate)
pip install -r requirements.txt
```

Add a key to `.env` (`Copy-Item .env.example .env`):
- **`GROQ_API_KEY`** — free at [console.groq.com](https://console.groq.com), used by the **web UI** (`app.py`).
- **`ANTHROPIC_API_KEY`** — used by the **CLI** (`client.py`).

## Run

**Web chat UI (Groq):**
```bash
chainlit run app.py -w          # → http://localhost:8200
```
Chat to use the file tools; slash commands for the rest:
`/dir` · `/read <f>` · `/stats` · `/tools` · `/review <f>` · `/tests <f>` · `/explain <f>` · `/docs` · `/help`.
You can also **attach a file** and say "review this file".

**Claude CLI (Anthropic):**
```bash
python client.py server.py
```

**Run the server directly / tests:**
```bash
python server.py
python tests\test_server.py     # or: python -m pytest
```

## How it works

- The server runs over **STDIO**; the client/UI spawn it as a subprocess.
- **Tools** are model-controlled (the agent calls them in its loop).
- **Resources** are app-controlled (`/dir`, `/read`, `/stats`).
- **Prompts** are user-controlled (`/review`, `/tests`, `/explain`, `/docs`).

---

Based on the IBM Skills Network *"Enhanced MCP Server"* lab, refactored into a
modular package and extended with more tools, resources, prompts, and a Groq UI.