logitech-sync-mcp: Instructions file for Codex

Repository instructions

These instructions apply to the entire repository.

Development environment

• Use Python 3.12 or newer.
• Use uv for dependency management, environments, and command execution. Do not use pip, pip-tools, Poetry, or manually edited lockfile entries.
• Keep uv.lock synchronized with pyproject.toml and use locked installs in CI.
• Prefer the source-tree launcher during development: uv run --no-editable python run_server.py.

Security boundary

• This MCP server is read-only. The targeted Logitech Sync Cloud API version exposes only GET /org/{orgId}/place; do not add mutation tools, generic HTTP proxy tools, or hidden write behavior.
• A future write capability requires an official API specification, a separate security review, precise tool-level confirmation semantics, and explicit documentation.
• Never commit .env, organization-specific configuration, certificates, private keys, credential exports, tokens, or real API payloads.
• Never print, copy, inspect, or include private-key contents in logs, tests, issues, or pull requests. It is acceptable to inspect file metadata and permissions without reading the key.
• Keep the vendor OpenAPI file local and ignored unless Logitech provides an explicit redistribution license.
• Use sanitized synthetic fixtures. Do not copy production inventory into tests/fixtures/.

MCP contracts

• Keep public MCP inputs flat and task-oriented. Do not expose deeply nested request objects or arbitrary upstream API parameters.
• Reject unknown input fields (extra="forbid") and retain additionalProperties: false in generated input schemas.
• Keep annotations accurate: all current tools are read-only, non-destructive, and idempotent.
• Return bounded human-readable content together with validated structured content. Do not leak certificate paths, key paths, credentials, or internal exception details.

Tests and verification

Run the same checks as CI before submitting a change: