Create wiki page 'Development'

2026-05-14 19:45:13 +00:00
parent 037f42af97
commit cf92cbd929
1 changed files with 153 additions and 0 deletions
@@ -0,0 +1,153 @@
+# 💻 Development
+
+Everything you need to contribute to the Strava MCP Server.
+
+---
+
+## Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- Docker (optional, for image builds)
+
+---
+
+## Setup
+
+```bash
+git clone https://git.hnrx.net/hnrx/strava-mcp-server.git
+cd strava-mcp-server
+
+# Install all dependencies (including dev tools)
+uv sync
+
+# Authenticate with your Strava account
+uv run auth
+
+# Start the server in STDIO mode
+uv run server
+
+# Start in HTTP mode
+MCP_TRANSPORT=http uv run server
+```
+
+---
+
+## Project Structure
+
+```
+strava-mcp-server/
+├── src/strava_mcp_server/
+│   ├── main.py              # Entry point & FastMCP setup
+│   ├── config.py            # Platform config path resolution
+│   ├── strava_client.py     # Strava API client with token refresh
+│   ├── utils.py             # Date/time helpers
+│   ├── get_token.py         # Interactive auth wizard
+│   └── tools/
+│       ├── __init__.py      # Tool registration
+│       ├── athlete.py
+│       ├── activities.py
+│       ├── clubs.py
+│       ├── routes.py
+│       ├── segments.py
+│       ├── segment_efforts.py
+│       ├── gear.py
+│       ├── prompts.py
+│       └── server_info.py
+├── tests/
+│   └── unit/                # Unit tests (offline, no API required)
+├── docs/
+│   └── DESIGN_DECISIONS.md
+├── website/                 # Landing page (deployed to S3)
+├── .gitea/workflows/        # CI/CD pipelines
+├── pyproject.toml
+└── Dockerfile
+```
+
+---
+
+## Testing
+
+### Unit Tests (offline, no Strava API required)
+
+```bash
+# Run all unit tests
+uv run pytest tests/unit/ -v
+
+# With coverage
+uv run pytest tests/unit/ --cov=strava_mcp_server
+```
+
+### MCP Inspector (interactive testing)
+
+```bash
+# STDIO mode — fastest
+npx @modelcontextprotocol/inspector uv run server
+
+# HTTP mode — connect to running server at localhost:8000
+```
+
+### Manual SSE Health Check
+
+```bash
+curl -v -X POST http://localhost:8000/mcp
+```
+
+---
+
+## Linting & Formatting
+
+```bash
+# Check for issues
+uv run ruff check src
+
+# Auto-fix issues
+uv run ruff check --fix src
+
+# Format code
+uv run ruff format src
+```
+
+---
+
+## Git Hooks
+
+Install the pre-configured hooks after cloning:
+
+```bash
+cp scripts/hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+cp scripts/hooks/pre-push   .git/hooks/pre-push   && chmod +x .git/hooks/pre-push
+```
+
+| Hook | Runs | Checks |
+|------|------|--------|
+| `pre-commit` | Before every commit | `ruff check` + `ruff format --check` on staged files |
+| `pre-push` | Before every push | Full unit test suite |
+
+Bypass with `git commit --no-verify` or `git push --no-verify`.
+
+---
+
+## Adding a New Tool
+
+1. Create or edit a file in `src/strava_mcp_server/tools/`
+2. Implement a `register(mcp, strava)` function
+3. Import and call it in `tools/__init__.py`
+
+Each tool should return a list with two items:
+- A `TextContent` with formatted Markdown (for the user)
+- An `EmbeddedResource` with JSON (for the LLM)
+
+See existing tools like `athlete.py` for reference.
+
+---
+
+## Building the Docker Image Locally
+
+```bash
+docker buildx build --platform linux/amd64,linux/arm64 -t strava-mcp-server:test .
+```
+
+---
+
+*Back to [Home](Home)*