Contributing
Run uv sync --extra cli --extra mcp --extra personal and uv run python -m unittest discover -s tests -t . -q before submitting changes. The personal extra installs Playwright; browser-dependent tests may require uv run playwright install chromium. CI runs Ruff across the Python tree, checks formatting of new and changed files against the existing .github/format-baseline.json, checks mypy against .github/mypy-baseline.txt, and runs the TypeScript interoperability smoke described in Development and testing. Format files you change and remove resolved type diagnostics from the baseline; do not add new deviations to a baseline merely to make CI pass.
For a new integration or a change to an upstream adapter:
- Record the authoritative source URLs, the access method, whether it is documented, and applicable terms and robots rules. Do not expand access or bypass authentication, CAPTCHA, or access restrictions. Review the rules again when they change.
- Identify public and personal data, local and remote side effects, and the correct startup profile. Keep personal credentials in the OS keyring and never put them in MCP arguments, fixtures, logs, or client configuration. Mark local state changes, downloads, and portal writes accurately in MCP annotations.
- Bound network concurrency, request rate, timeouts, response sizes, retries, pagination, and cache memory. Respect provider rate limits and
Retry-After. State when limits are per process rather than shared across deployments. - Add synthetic fixtures representing normal, empty, partial, malformed, and changed upstream responses. Check parsing and output schemas, cache behavior on failures, pagination and incomplete coverage. Avoid recording personal data, cookies, or signed URLs in fixtures.
- Include source and retrieval-time metadata where available, distinguish missing data from empty results, and return actionable errors without provider secrets or invented data. Treat external content as untrusted data, not instructions.
- Run targeted unit and protocol tests. If live access is appropriate and authorized, run bounded read-only smoke checks, report when and what was tested, and do not claim untested operations work. Do not perform portal writes or upload user files as a routine smoke test.
CLI and MCP interfaces
Run uv run ntu --help for the local CLI and uv run ntu mcp for the stdio server. Test direct commands without a transport, and keep local action confirmation and MCP host confirmation covered separately. Expose service capabilities through family commands; keep temporary One Stop draft operations inside standalone workflows. Preserve the existing configuration and keyring entries.
Python package layout
Keep service operations independent of the CLI and MCP transports and register them in the shared catalog. When a responsibility grows into several related modules, group those modules in a named subpackage such as client, models, parser, services, or a domain-specific package. Keep transport, parsing, domain rules, and operation orchestration in their respective layers. Update imports to canonical package paths when reorganizing, and use __init__.py for the package's actual public exports. Do not retain old module-path shims unless an explicit external API requires them. Do not create folders solely to shorten files or make every package contain empty layers.
The public hosted endpoint is unauthenticated and must never register personal tools. A Vercel gateway limit is a separate deployment control: process-local outbound pacing does not enforce a per-client limit across replicas. Review deployed settings and upstream 429s before release.