From c1f01ea72fd2065a28526cf6d5eb788aa7664920 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Aug 2026 06:22:11 +0000 Subject: [PATCH] Add installation guides: Giordano fix + full Windows install - docs/GIORDANO-FIX.md: step-by-step for next session with Giordano - docs/INSTALL-WINDOWS.md: complete clean install guide for any Windows machine --- docs/GIORDANO-FIX.md | 104 ++++++++++++++++++ docs/INSTALL-WINDOWS.md | 233 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 337 insertions(+) create mode 100644 docs/GIORDANO-FIX.md create mode 100644 docs/INSTALL-WINDOWS.md diff --git a/docs/GIORDANO-FIX.md b/docs/GIORDANO-FIX.md new file mode 100644 index 0000000..0f2092f --- /dev/null +++ b/docs/GIORDANO-FIX.md @@ -0,0 +1,104 @@ +# Giordano Desktop Fix — Next Session + +**Date:** 2026-08-03 +**Machine:** Windows, AMD Ryzen 3 2200G, 8GB RAM, user `giord`, Python 3.14 +**Issue:** Claude Desktop MCP connector fails — wrong MCP package version installed + +## Prerequisites + +- Diligence app folder at `C:\Users\giord\Downloads\Diligence-main` +- Claude Desktop installed (Microsoft Store version) +- Node.js installed +- `mcp_stdio.py` already in the Diligence-main folder +- Claude Desktop config already set at both paths: + - `%APPDATA%\Claude\claude_desktop_config.json` + - `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json` + +## Step 1 — Clean up old MCP packages + +```powershell +cd "$env:USERPROFILE\Downloads\Diligence-main" +pip uninstall mcp mcp-cli fastmcp -y +``` + +## Step 2 — Fix the import in server.py + +The old code imports from the wrong package. Run this once: + +```powershell +(Get-Content diligence\mcp\server.py) -replace 'from mcp\.server\.fastmcp import FastMCP', 'from fastmcp import FastMCP' | Set-Content diligence\mcp\server.py +``` + +## Step 3 — Install the correct packages + +```powershell +pip install "fastmcp>=3.0.0" +pip install tzdata +``` + +## Step 4 — Test the MCP stdio script + +```powershell +python mcp_stdio.py +``` + +- **If it hangs with no output** → success. Ctrl+C to stop. +- **If it throws an error** → paste the traceback. + +## Step 5 — Start Diligence + +```powershell +python -m diligence +``` + +Confirm **both** lines appear: +- `Diligence running at http://localhost:8000` +- `MCP: http://localhost:3001/sse` + +## Step 6 — Restart Claude Desktop + +```powershell +Get-Process *claude* | Stop-Process -Force +``` + +Reopen Claude Desktop from the Start menu. Look for a tools/hammer icon indicating MCP connected. + +## Step 7 — Test + +In Claude Desktop, type: + +> What's my fitness status today? + +Claude should call the `get_context` tool and return fitness data. + +Also test a write operation: + +> Log a 30 minute workout called Morning Run + +--- + +## Fallback: Built-in AI Coach (no Claude Desktop needed) + +If Claude Desktop MCP continues to have issues, use the built-in coach: + +1. Go to `http://localhost:8000/agent` in the browser +2. Under "Option 1 — Built-in AI Coach", click **Get key** next to **OpenRouter** +3. Sign up with Google (free, 26 free models available) +4. Copy the API key +5. In Diligence, go to **Settings > Integrations > AI Coaching** +6. Paste the key and select a model +7. Use the **Coach** tab in the bottom nav + +This runs entirely inside the app — no external tools needed. + +--- + +## Known Issues on This Machine + +| Issue | Fix | Status | +|-------|-----|--------| +| tzdata not in pip dependencies | pip install tzdata manually | Pending GitHub push | +| mcp v2.0.0 removed FastMCP import | Switch to standalone fastmcp package | Fixed in subo repo, pending GitHub | +| GitHub push token expired | Need new PAT with repo scope | Not yet done | +| Migration warning: NOT NULL on point_rules.description | Non-fatal, cosmetic | Low priority | +| PowerShell QuickEdit mode pauses the app | Right-click title bar, Properties, uncheck QuickEdit | Told user | diff --git a/docs/INSTALL-WINDOWS.md b/docs/INSTALL-WINDOWS.md new file mode 100644 index 0000000..e3e27ee --- /dev/null +++ b/docs/INSTALL-WINDOWS.md @@ -0,0 +1,233 @@ +# Diligence Fitness — Windows Installation Guide + +Complete installation from a clean Windows machine with no dependencies. + +--- + +## 1. Install Python + +Download Python from [python.org/downloads](https://www.python.org/downloads/). +Use the latest **3.12** or **3.13** release (3.14 works but is bleeding edge). + +**During installation, check "Add Python to PATH"** — this is critical. + +Verify in a new PowerShell window: + +```powershell +python --version +``` + +Should show `Python 3.12.x` or similar. + +--- + +## 2. Install Node.js (required for Claude Desktop MCP) + +Download the LTS version from [nodejs.org](https://nodejs.org). Run the installer with defaults. + +Verify in a **new** PowerShell window: + +```powershell +node --version +``` + +Skip this step if you only plan to use the built-in AI Coach (see Step 7b). + +--- + +## 3. Download Diligence + +Since Git is not required, download as a ZIP: + +```powershell +cd "$env:USERPROFILE\Downloads" +Invoke-WebRequest -Uri "https://github.com/DiligenceWorks/Diligence/archive/refs/heads/main.zip" -OutFile Diligence.zip +Expand-Archive Diligence.zip -DestinationPath . +cd Diligence-main +``` + +--- + +## 4. Install Diligence and dependencies + +Install the app with MCP support and Windows timezone data: + +```powershell +cd "$env:USERPROFILE\Downloads\Diligence-main" +pip install ".[mcp]" +pip install tzdata +``` + +**Note:** The `tzdata` package is required on Windows because Python's `zoneinfo` +module has no system timezone database. Without it, the Home and Keto pages will +show "failed to load." + +The `.[mcp]` extra installs the MCP server for AI agent integration. If you +only want the web app without AI features, use `pip install .` instead. + +--- + +## 5. Start Diligence + +```powershell +cd "$env:USERPROFILE\Downloads\Diligence-main" +python -m diligence +``` + +You should see: + +``` +Diligence running at http://localhost:8000 + Data: C:\Users\USERNAME\.diligence + MCP: http://localhost:3001/sse + Press Ctrl+C to stop +``` + +Open `http://localhost:8000` in your browser. Create an account on the registration page. + +**Important:** Do not click inside the PowerShell terminal window while the app is +running. Windows QuickEdit mode will pause the process. To prevent this permanently: +right-click the PowerShell title bar, select Properties, uncheck "QuickEdit Mode." + +--- + +## 6. Create the MCP stdio launcher + +Create the file `mcp_stdio.py` in your Diligence-main folder: + +```powershell +Set-Content "$env:USERPROFILE\Downloads\Diligence-main\mcp_stdio.py" @' +from diligence.mcp.server import create_mcp_server +mcp = create_mcp_server(api_url="http://localhost:8000") +mcp.run(transport="stdio") +'@ +``` + +Test it (Diligence must be running in another terminal): + +```powershell +cd "$env:USERPROFILE\Downloads\Diligence-main" +python mcp_stdio.py +``` + +If it hangs with no output, that means success (stdio is waiting for input). Press Ctrl+C to stop. + +--- + +## 7a. Connect Claude Desktop (free, MCP agent) + +### Install Claude Desktop + +Download from [claude.ai/download](https://claude.ai/download) or install from the Microsoft Store. +Sign in with a free Claude account. + +### Configure MCP + +Determine which install you have and set the config: + +**Standard install:** + +```powershell +mkdir "$env:APPDATA\Claude" -ErrorAction SilentlyContinue +Set-Content "$env:APPDATA\Claude\claude_desktop_config.json" @' +{ + "mcpServers": { + "diligence": { + "command": "python", + "args": ["mcp_stdio.py"], + "cwd": "DILIGENCE_PATH" + } + } +} +'@ +``` + +**Microsoft Store install:** + +```powershell +Set-Content "$env:LOCALAPPDATA\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json" @' +{ + "mcpServers": { + "diligence": { + "command": "python", + "args": ["mcp_stdio.py"], + "cwd": "DILIGENCE_PATH" + } + } +} +'@ +``` + +Replace `DILIGENCE_PATH` with the actual path, e.g. `C:\\Users\\giord\\Downloads\\Diligence-main`. +Note the double backslashes in JSON. + +**If you are unsure which install you have**, set both configs — only the correct one will be read. + +### Start and test + +1. Start Diligence in a terminal (`python -m diligence`) +2. Quit Claude Desktop fully (right-click system tray icon > Quit, or `Get-Process *claude* | Stop-Process -Force`) +3. Reopen Claude Desktop +4. Look for a tools/hammer icon indicating MCP connected +5. Type: "What's my fitness status today?" + +--- + +## 7b. Alternative: Built-in AI Coach (no extra apps needed) + +If Claude Desktop MCP is not working or you prefer a simpler setup: + +1. Get a free API key from one of these providers: + - **OpenRouter** (openrouter.ai/keys) — 26 free models, sign up with Google + - **Groq** (console.groq.com) — free tier, fast inference + - **Google AI Studio** (aistudio.google.com) — free Gemini API key +2. In the Diligence browser app, go to **Settings > Integrations > AI Coaching** +3. Paste your API key and select a model +4. Use the **Coach** tab in the bottom navigation + +--- + +## Daily Usage + +Each time you want to use Diligence: + +```powershell +cd "$env:USERPROFILE\Downloads\Diligence-main" +python -m diligence +``` + +Open `http://localhost:8000` in your browser. The app runs until you press Ctrl+C. + +If using Claude Desktop, make sure Diligence is running first, then open Claude Desktop. + +--- + +## Updating + +To get the latest version: + +```powershell +cd "$env:USERPROFILE\Downloads" +Remove-Item -Recurse -Force Diligence-main +Invoke-WebRequest -Uri "https://github.com/DiligenceWorks/Diligence/archive/refs/heads/main.zip" -OutFile Diligence.zip +Expand-Archive Diligence.zip -DestinationPath . -Force +cd Diligence-main +pip install ".[mcp]" +pip install tzdata +``` + +Your data is stored in `~\.diligence\` and is preserved across updates. + +--- + +## Troubleshooting + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Home/Keto pages show "failed to load" | Missing tzdata | `pip install tzdata` | +| "No module named diligence" | Not in the right directory | `cd "$env:USERPROFILE\Downloads\Diligence-main"` | +| "No module named uvicorn" | Dependencies not installed | `pip install ".[mcp]"` | +| App stops when clicking terminal | PowerShell QuickEdit mode | Right-click title bar > Properties > uncheck QuickEdit | +| Claude Desktop MCP "Server disconnected" | Wrong MCP package or transport | See Step 6 for stdio setup | +| MCP "not valid configurations" | Config uses url instead of command | Use the stdio config format (Step 7a) | +| Claude Desktop MCP "not available" | MCP extras not installed | `pip install ".[mcp]"` |