nightscout: Instructions file for Claude Code

MCP Nightscout

FastMCP server providing tools for diabetes type 1 management via Nightscout API.

Key files

• src/server.py — MCP tools + auth middleware + health endpoint
• src/nightscout_client.py — HTTP client for Nightscout REST API v1
• src/log_filter.py + src/log_config.yaml — JSON logging, filters /health
• tests/test_auth.py — auth middleware tests (pytest-asyncio)

Stack

• Python 3.12, FastMCP, httpx, uvicorn
• Docker → GitLab CI → Kubernetes (deploy/ templates)

Environment variables

• NIGHTSCOUT_URL — Nightscout instance base URL
• NIGHTSCOUT_API_SECRET — API secret (hashed SHA1)
• NIGHTSCOUT_TOKEN — readable token (alternative to api-secret)
• NIGHTSCOUT_TIMEOUT — request timeout (default 30s)
• MCP_AUTH_TOKEN — MCP server auth token (optional for local dev)

Adding a new tool

1. If it needs a new API call, add it to nightscout_client.py
2. Add @mcp.tool() function in server.py with clear docstring
3. Run docker compose up --build to test locally

2. Coding Practices (Clean Code)

• SOLID & Modular: Use Clean Code principles. E.g. keep functions small and focused on one task.
• No Redundancy: Avoid "huge texts" for small clarifications. Keep code self-documenting.
• Formatting:
  • Black for Python (max line length 79).

3. Testing

Unit Test Writing Guidelines

1. Structure Every Test with Given-When-Then comments

• Given: set up preconditions and test data.
• When: execute one behavior/action under test.
• Then: assert the observable outcome.
• If action and expectation are tightly coupled (for example exception checks), a combined When/Then block is acceptable.

2. Name Tests as Readable Behavior Statements

• Use names that describe scenario plus expected outcome.
• Recommended pattern: scenario_expected_result.
• Prefer descriptive names over generic names like test1 or shouldWork.
• A reader should understand what the test proves without reading the full body.

3. Keep One Behavior per Test

• Each test should validate one rule or behavior.
• Avoid mixing unrelated assertions in one test.
• Split into multiple tests if multiple behaviors need verification.