initial setup:

uv init will work only at the top folder Don’t run it in subfolders, or you’ll end up with multiple environments. Use uv run inside subfolders, and it will still respect the root .venv.

How to Create .venv with uv

uv venv .venv

Then activate it: Linux/Mac: source .venv/bin/activate Windows PowerShell: Use Activate.ps1 (PowerShell script), not just activate. .venv\Scripts\activate ..venv\Scripts\Activate.ps1

PowerShell may prevent running scripts. If you see an error like “running scripts is disabled”, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ..venv\Scripts\Activate.ps1

If you’re in Command Prompt (cmd.exe), use: .venv\Scripts\activate.bat

The layering, concretely

┌─────────────────────────────────────────────────────────┐ │ main.py (HOST) │ │ - choose_model() │ │ - get_question() │ │ - creates ProjectAgent(model=...) │ │ - calls agent.ask(question) │ └───────────────────────┬─────────────────────────────────┘ │ agent.ask(question) (in-process call) ┌───────────────────────▼───────────────────────────────────┐ │ agent.py → ProjectAgent (MCP CLIENT + LLM loop) │ │ - opens stdio_client(server_params) │ │ - ClientSession.initialize() / list_tools() / call_tool()│ │ - drives OpenAI tool-calling loop until final answer │ └───────────────────────┬───────────────────────────────────┘ │ stdio pipes (JSON-RPC under the hood) ┌───────────────────────▼───────────────────────────────────┐ │ project_server.py (MCP SERVER, spawned as subprocess) │ │ - get_project_plan() │ │ - get_milestones(status) │ │ - get_raid_items(severity) │ │ - get_blockers() │ └───────────────────────────────────────────────────────────┘

Project layout

Put all three files in the same folder: AI-project-status-MVP1/ ├── project_server.py ← MCP SERVER (subprocess, exposes 4 tools) ├── agent.py ← MCP CLIENT + tool-calling loop (ProjectAgent class) ├── main.py ← HOST (prompts, model choice, user input only) ├── project_client_test.py ← standalone debug tool (manual tool calls, no LLM)

Install dependencies

pip install "mcp[cli]" anthropic

or, if using the OpenAI version:

pip install "mcp[cli]" openai

if version issue comes

..venv\Scripts\python.exe -m ensurepip --upgrade ..venv\Scripts\python.exe -m pip install --upgrade pip ..venv\Scripts\python.exe -m pip install "mcp[cli]<2" openai ..venv\Scripts\python.exe -m pip show mcp python -c "from mcp.server.fastmcp import FastMCP; print('ok')"

Execution steps (current MVP1)

1. Activate your venv (from the project folder): ..venv\Scripts\Activate.ps1

2. Confirm you're in the right env (quick sanity check after all the earlier path issues): Get-Command python python -m pip show mcp openai

Both should resolve to paths inside .venv.

3. Set your OpenAI key for this session (or use the .env + python-dotenv approach) $env:OPENAI_API_KEY = "sk-..."

4. Confirm all three files are together: Get-ChildItem *.py

5. Run it: (From AI-project-status-MVP1) python main.py

You'll be prompted to pick a model (defaults to gpt-4o-mini) and enter a question (defaults to the status-summary prompt). main.py calls into agent.py, which spawns project_server.py as a subprocess automatically — you don't run the server separately.