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
This commit is contained in:
parent
b63e5f7f5b
commit
c1f01ea72f
2 changed files with 337 additions and 0 deletions
104
docs/GIORDANO-FIX.md
Normal file
104
docs/GIORDANO-FIX.md
Normal file
|
|
@ -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 |
|
||||||
233
docs/INSTALL-WINDOWS.md
Normal file
233
docs/INSTALL-WINDOWS.md
Normal file
|
|
@ -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]"` |
|
||||||
Loading…
Add table
Add a link
Reference in a new issue