# MCP-Based Developer Assistant

## Overview

A tool-using developer assistant that exposes three tools through an MCP-style schema: `read_file`, `list_tests` and `run_tests`. `GET /tools` lists them and `POST /call` invokes one, while any request to apply changes is refused. A versioned `/v1` ops API adds workspaces, tenant isolation, job approval and audit, and a pytest suite runs in GitHub Actions.

- **Built with:** Python, MCP, pytest, GitHub Actions
- **Scope:** Local laptop lab; it does not call a hosted model and does not apply production changes.

<!-- project-guide:start -->
## Project guide

[Project architecture](PROJECT_ARCHITECTURE.md) · [Interview questions and answers](INTERVIEW_QA.md)

Use the architecture document for the component diagram, implementation boundaries, and verification entry points. The interview guide includes source-backed answers and project walkthroughs.

### Implementation map

| Component | Responsibility |
| --- | --- |
| [`src/mcpdev/main.py`](src/mcpdev/main.py) | HTTP handlers: `GET /healthz`, `GET /tools`, `POST /call` |
| [`src/mcpdev/mcp.py`](src/mcpdev/mcp.py) | Functions: `list_tools`, `call` |
| [`requirements.txt`](requirements.txt) | Implementation or supporting configuration |
| [`src/mcpdev/__init__.py`](src/mcpdev/__init__.py) | Implementation or supporting configuration |
| [`tests/test_mcp.py`](tests/test_mcp.py) | Executable checks and regression examples |
| [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | GitHub Actions job definitions |
| [`README.md`](README.md) | Project explanations or operating notes |

### Local setup and verification

From the repository root (the commands follow the checked-in manifests):

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pytest -q
```

To serve the FastAPI application locally, install the server separately if it is not already available:

```bash
python -m pip install uvicorn
PYTHONPATH=src python -m uvicorn mcpdev.main:app --reload
```

<!-- project-guide:end -->

Level: 10 — MCP & Tool-Using Agents

Skills: Python, tool schema, no apply

Tools: read_file, list_tests, run_tests. Apply is refused.

```bash
pip install -r requirements.txt
pytest -q
```

This is a local laptop proof. It does not call a hosted model and it does not apply production changes.

## Ops plane

Workspaces, tenant isolation, job approval, and audit live under `/v1`. Production apply is refused. See `docs/ARCHITECTURE.md`.

## Documentation checks

Project architecture, interview guides, and local source links are checked automatically on pushes and pull requests. Run the same check locally:

```bash
python3 .github/scripts/validate_project_docs.py
```

See [service improvements and local run instructions](docs/UPGRADES.md).