{
  "markdown": "# UpToCode\n\n<!-- mcp-name: io.github.DDYRich72/uptocode -->\n\n[![PyPI version](https://img.shields.io/pypi/v/uptocode.svg)](https://pypi.org/project/uptocode/)\n[![Scanned with UpToCode](https://img.shields.io/badge/scanned%20with-UpToCode-175cd3)](https://github.com/DDYRich72/UpToCode)\n\nUpToCode is a design-time architecture-quality scanner for Python and TypeScript agent applications. It finds missing execution bounds, run budgets, approvals, validation, resilience controls, evals, and observability; explains the evidence; and produces an approval-driven plan for Codex without rewriting source code.\n\nThe product is deliberately narrower than a general agent-security scanner. Version 1.7 recognizes OpenAI, Anthropic, CrewAI, PydanticAI, LlamaIndex, LangGraph, conservative custom Python/TypeScript loops, and positive evidence of unbounded context growth. Static scans are local and offline. Optional GPT‑5.6 judgment remains explicit, bounded, redacted, and code-sharing gated.\n\n> The Python distribution, import package, and command are all `uptocode`. Version 1.0.0\n> is the published baseline; this source tree is prepared as 1.10.0 for the operator-gated Batch 3 release train.\n\n## Install locally\n\nUpToCode requires Python 3.11 or newer. Install the verified 1.0 release from PyPI:\n\n```text\npython -m pip install \"uptocode==1.0.0\"\nuptocode --help\n```\n\nFor repository development, use the editable test environment:\n\n```text\npython -m pip install -e \".[test]\"\nuptocode --help\n```\n\nAll ordinary tests are mocked/offline:\n\n```text\npython -m pytest -q\npython scripts/acceptance.py\n```\n\n## Judge test build\n\nThe repository and package are public. No hosted credential or paid model call is required\nfor the complete offline test build.\n\n```text\ngit clone https://github.com/DDYRich72/UpToCode.git\ncd UpToCode\npython -m venv .venv\n```\n\nActivate the environment with `.venv\\Scripts\\activate` on Windows PowerShell or\n`source .venv/bin/activate` on POSIX, then run:\n\n```text\npython -m pip install --upgrade pip\npython -m pip install -e \".[test]\"\nuptocode scan fixtures/bad_python --fail-on critical\nuptocode scan fixtures/bad_python --format json --output report.json\nuptocode review report.json --approve AA001,AA003 --reject AA012 --non-interactive\nuptocode plan report.json --manifest .uptocode/manifest.json --output FIXPLAN.md\npython scripts/acceptance.py\n```\n\nThe first scan intentionally exits `1` because the fixture contains critical findings.\nThe remaining commands produce a report-bound review manifest and an approved-only\n`FIXPLAN.md`; they do not edit the fixture. To inspect the local MCP surface, run\n`uptocode serve --transport stdio --root .` from an MCP client or use the JSON\nregistration under [MCP registration](#mcp-registration). `python scripts/acceptance.py`\nalso launches a real stdio server, lists all ten tools, and calls `check_loop` offline.\n\nThe submitted-content hosted transport is deployed at\n`https://uptocode-mcp-1015314816960.us-central1.run.app/mcp`. Its bearer credential is\nissued separately and read from `UPTOCODE_API_KEY`; never commit it or enter it into the\nwebsite. The immutable production revision passed readiness, unauthorized-access, AA001,\ntool-discovery, judgment-gate, rate-limit, and payload-free-log checks. Hosted judgment is\noff, no OpenAI key is attached, and verification made zero paid model calls.\n\n## Scan, review, plan\n\n```text\nuptocode scan PATH [--format terminal|json|html|github|sarif] [--output FILE]\n                         [--judgment --send-code]\n                         [--fail-on critical|warning|info]\n                         [--include-experimental] [--share-safe]\n                         [--baseline FILE|--update-baseline FILE]\n                         [--changed-since REF] [--select RULES] [--ignore RULES]\n                         [--exclude GLOB] [--severity RULE=LEVEL]\n                         [--fail-on-analysis-warning] [--github-summary PATH]\n                         [--verbose]\nuptocode review REPORT [--approve IDS|--approve-all] [--reject IDS]\n                              [--reuse MANIFEST] [--non-interactive]\nuptocode plan REPORT --manifest MANIFEST [--output FIXPLAN.md]\nuptocode fix REPORT --manifest MANIFEST --runner codex|command\n                    [--command TEMPLATE] [--verify-command COMMAND] [--apply]\nuptocode serve --transport stdio --root PATH\nuptocode serve --transport streamable-http --mode hosted\n```\n\nScanning, review, planning, and the default fix preview are non-mutating:\n\n```text\nuptocode scan . --format json --output report.json\nuptocode review report.json --approve AA001,AA003 --reject AA012 --non-interactive\nuptocode plan report.json --manifest .uptocode/manifest.json --output FIXPLAN.md\nuptocode fix report.json --manifest .uptocode/manifest.json --runner codex\n```\n\n`review` binds decisions to the exact report fingerprint. `plan` refuses a mismatched manifest and includes only approved findings. Neither command edits the scanned repository.\n`fix` is also a no-write dry-run unless `--apply` is supplied. The applying path requires\na clean Git checkout, creates one retained `uptocode/fix-<fingerprint12>` branch/worktree\nper approved finding, invokes only the selected external runner there, verifies fingerprint\nabsence, and never commits, merges, deletes work, or changes the invoking checkout.\n\nExit codes are `0` for no configured threshold breach, `1` for a finding at or above `--fail-on` (or a requested analysis-warning gate), and `2` for invalid configuration or an unrecoverable scan error. Experimental findings remain visible but require `--include-experimental` to affect `--fail-on`. `--share-safe` sanitizes JSON, HTML, or SARIF for distribution while retaining the repository revision. Baseline 2.1 reports new, aging, and resolved debt and preserves `first_seen` when updated. Suppressions may include `owner`, quoted `reason`, and an inclusive `expires` date. HTML requires `--output`. GitHub workflow commands escape untrusted command data and properties. SARIF 2.1.0 omits absent fields, declares default rule levels, and carries stable partial fingerprints. `--github-summary PATH` appends a bounded Markdown summary; when `GITHUB_STEP_SUMMARY` is set, the summary is appended there automatically.\n\n## Pre-commit\n\n```yaml\nrepos:\n  - repo: https://github.com/DDYRich72/UpToCode\n    rev: v1.1.0\n    hooks:\n      - id: uptocode\n```\n\nRun `pre-commit install`, then use `pre-commit run uptocode --all-files`. To copy the\nproject badge into your own README:\n\n```markdown\n[![Scanned with UpToCode](https://img.shields.io/badge/scanned%20with-UpToCode-175cd3)](https://github.com/DDYRich72/UpToCode)\n```\n\n## GitHub Action\n\nThe repository ships a composite Action that installs UpToCode from the Action checkout,\nruns the scan, uploads SARIF with `always()`, and only then returns the preserved scanner\nexit code:\n\n```yaml\npermissions:\n  contents: read\n  security-events: write\n\nsteps:\n  - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7\n  - uses: DDYRich72/UpToCode@v1.0.0\n    with:\n      path: .\n      fail-on: critical\n      version: source\n      upload-sarif: \"true\"\n```\n\n`version: source` installs from the checked-out Action source. An exact semantic version,\nsuch as `1.0.0`, installs the matching `uptocode` PyPI release. Set\n`upload-sarif: \"false\"` when code-scanning\nupload is not desired; otherwise the calling workflow needs `security-events: write`.\n\nExample terminal output:\n\n```text\nUpToCode scan\nCoverage: 1/1 files analyzed\nFindings: 11 | Warnings: 0 | Redactions: 3\n[CRITICAL] AA001 agent.py:21 - Unbounded agent loop\n[CRITICAL] AA003 agent.py:11 - Ungated destructive action\n```\n\n## Privacy model\n\n- Static scanning is the default and makes no network calls.\n- `--judgment` is rejected unless `--send-code` is also present.\n- Judgment sends only normalized evidence and bounded, redacted excerpts, grouped once per candidate rule. Requests use `gpt-5.6`, Pydantic Structured Outputs, `store=false`, a 2,000-token output ceiling, a 30-second timeout, and a six-rule call budget.\n- Recognized OpenAI keys, AWS access keys, bearer tokens, email addresses, and US Social Security numbers are replaced before report or judgment output. Detection is intentionally narrow and is not a substitute for a dedicated secret/PII scanner.\n- Nested `.gitignore` files, default build/dependency/generated exclusions, `.uptocode.yml`, 1 MiB per-file and 4 MiB aggregate limits, binary/non-Python exclusion, and explicit suppressions are honored. Production UpToCode source is gated at zero suppressions.\n- Refusal, timeout, authentication failure, or API failure never deletes static results; the report records `partial` or `failed` judgment status and an analysis warning.\n\nNo live API call is part of the offline test or acceptance suite. The submission smoke test requires a key and separate approval for paid usage.\n\n## Rules\n\n| ID | Architecture defect | Tier | Severity | Primary guidance |\n|---|---|---|---|---|\n| AA001 | Unbounded agent loop | Static | critical | [Agents SDK runner](https://openai.github.io/openai-agents-python/ref/run/) |\n| AA002 | Missing output/run budget controls | Static | critical | [OpenAI practical guide](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) |\n| AA003 | Ungated destructive action | Static + judgment | critical | [Agents SDK approvals](https://openai.github.io/openai-agents-python/human_in_the_loop/), [OpenAI safety](https://developers.openai.com/api/docs/guides/agent-builder-safety) |\n| AA004 | Unvalidated tool arguments | Static | critical | [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling), [Anthropic tool definitions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) |\n| AA005 | Raw untrusted content in prompts | Judgment | critical | [OpenAI safety](https://developers.openai.com/api/docs/guides/agent-builder-safety), [Anthropic guardrails](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks) |\n| AA006 | Secret or narrow PII exposure | Static | critical | [OpenAI safety](https://developers.openai.com/api/docs/guides/agent-builder-safety) |\n| AA007 | Missing timeout, retry, or retry backoff | Static | warning | [OpenAI practical guide](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) |\n| AA008 | Unjustified orchestration complexity | Judgment | warning | [Anthropic effective agents](https://www.anthropic.com/engineering/building-effective-agents), [OpenAI practical guide](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) |\n| AA009 | Poor tool schema | Judgment | warning | [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling), [Anthropic tool definitions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) |\n| AA010 | Unvalidated model output before side effect | Static + judgment | warning | [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling), [OpenAI safety](https://developers.openai.com/api/docs/guides/agent-builder-safety) |\n| AA011 | No agent eval coverage | Static + judgment | warning | [OpenAI evals](https://developers.openai.com/api/docs/guides/evals), [Google ADK evaluation](https://adk.dev/evaluate/) |\n| AA012 | No agent observability | Static | info | [Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) |\n| AA013 | Unbounded context growth | Static | warning | [Anthropic effective agents](https://www.anthropic.com/engineering/building-effective-agents), [OpenAI practical guide](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) |\n| AA014 | Network MCP without authentication | Static | critical | [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), [FastMCP token verification](https://gofastmcp.com/v2/servers/auth/token-verification) |\n| AA015 | MCP tools without annotations | Static | warning | [MCP tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) |\n| AA016 | Non-strict MCP tool arguments | Static | warning | [MCP tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools), [Pydantic configuration](https://docs.pydantic.dev/latest/api/config/#pydantic.config.ConfigDict.extra) |\n| AA017 | Undifferentiated tool errors | Static + judgment (experimental) | warning | [MCP tool errors](https://modelcontextprotocol.io/specification/2025-11-25/server/tools), [Claude tool-call errors](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls) |\n| AA018 | Prompt-only policy enforcement | Static + judgment (experimental) | warning | [NIST AI 600-1](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf), [OWASP Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/) |\n\nEach static verdict requires recognized syntax and source-backed evidence. Unsupported or dynamic constructs produce coverage gaps or analysis warnings; they are never silently declared clean.\n\n## VS Code\n\nThe standalone extension in `editor/vscode-uptocode/` scans Python documents on save and\nturns valid UpToCode JSON findings into file diagnostics. It runs no daemon or background\nrepository scan and provides no auto-fix. Build and install a local package with:\n\n```text\ncd editor/vscode-uptocode\nnpm ci\nnpm run verify\ncode --install-extension uptocode-vscode.vsix\n```\n\nConfigure `uptocode.executable`, `uptocode.extraArgs`, and `uptocode.failOn` in VS Code.\nMarketplace publication remains operator-only.\n\n## Supported and unsupported constructs\n\nRecognized evidence includes:\n\n- OpenAI `Runner.run`/`run_sync` limits: omitted `max_turns` is clean because the SDK default is bounded; explicit numeric limits are clean; `max_turns=None` is flagged.\n- LangGraph `recursion_limit` when statically resolvable.\n- `while True` loops with detectable exits, constant bounds, and simple recursive base cases.\n- OpenAI Responses model calls, output caps, client/call timeouts, bounded client retries, and simple source-level run budgets.\n- `@function_tool` approvals, its model-controlled parameters reaching common SQL/shell/file/network sinks, parameter-linked validation, agent eval markers/tests, and nearby logging/tracing evidence.\n- Anthropic Messages/Agent SDK, CrewAI, PydanticAI, and LlamaIndex framework contracts documented under `docs/frameworks/`.\n- Tree-sitter analysis for `.ts`, `.tsx`, and `.mts`: custom infinite loops, OpenAI Agents JS `maxTurns`, LangGraph.js `recursionLimit`, token/timeout/retry options, Zod tool parameters, and tracing imports.\n\nKnown limitations:\n\n- TypeScript coverage is intentionally limited to AA001, AA002, AA004, AA007, and AA012;\n  every other rule is reported per-language as not applicable.\n- Dynamic imports, metaprogramming, dispatch beyond the supported one-hop project call graph, and runtime-only behavior remain inconclusive and produce coverage warnings when recognized.\n- Static side-effect and schema analysis is conservative and can produce false positives; findings should be reviewed before planning.\n- Secret/PII recognition covers a small explicit pattern set, not arbitrary credentials or personal data.\n- No instruction-file linting, runtime tracing service, in-process source-changing codemod,\n  browser repository upload, or account system. Explicit `fix --apply` remediation is\n  delegated to an external runner in an isolated Git worktree.\n\n## Configuration\n\nCreate `.uptocode.yml` at the scan root:\n\n```yaml\nexclude:\n  - generated/\n  - vendor/\nmax_file_size: 1048576\n```\n\nPaths in reports are normalized relative to the scan root. Report 2.2 coverage records aggregate and per-language discovered/analyzed files, detected frameworks, evaluated/not-applicable rules, suppressions, warnings, judgment status, and redaction counts.\n\nStandalone HTML reports include keyboard-accessible Approve/Reject decisions and download\na report-bound ReviewManifest 2.0 locally through a Blob. The report performs no network\nrequests; `uptocode plan` remains the only manifest consumer and never edits source.\n\nGenerate matching HTML and JSON from one scan before reviewing:\n\n```text\nuptocode scan . --format html --output report.html --json-output report.json\n# Review report.html and download uptocode-review-manifest.json\nuptocode plan report.json --manifest uptocode-review-manifest.json --output FIXPLAN.md\n```\n\n## MCP registration\n\nRun the stdio server directly with `uptocode serve`, or register the module with an MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"uptocode\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"uptocode.mcp_server\"],\n      \"cwd\": \"/absolute/path/to/this/repository\"\n    }\n  }\n}\n```\n\nLocal mode exposes repository/file/source/diff audits, strict schema and loop checks, the rule catalog, review, and FIXPLAN generation. It is bounded to the configured canonical workspace root, including symlink defense, and may load only explicitly trusted local rulepacks.\n\nHosted Streamable HTTP mode registers only submitted-content tools. It has no repository or\nfilesystem-path tools, never persists submitted code or results, and requires private-beta\nbearer keys configured as SHA-256 digests in `UPTOCODE_API_KEY_HASHES`. Authenticated\nrequests use an in-memory per-key token bucket (`UPTOCODE_RATE_LIMIT_PER_MINUTE`, default\n`30`); excess requests return `429` with `Retry-After`. Logs attribute traffic only to an\neight-character digest prefix. Hosted judgment is rejected unless\n`UPTOCODE_HOSTED_JUDGMENT=true`; the default is `false`. The double-consent\n`judgment=true, send_code=true` rule still applies when the global gate is enabled.\n\nLocal mode resolves its canonical workspace root once when the server is created. Relative\nand absolute file, repository, and diff-base paths are all contained against that same root,\nincluding symlink resolution. The pinned MCP SDK compatibility guard fails server startup\nwith the installed SDK version if the strict-schema private contract changes; the upgrade\nprocedure is documented in `docs/operations.md`.\n\nThe functional landing and connection generator live in `web/`. `/connect` generates local stdio or hosted Codex MCP configuration; bearer keys remain in the user's local environment and are never entered into or transmitted by the page.\n\n## UpToCode audits itself\n\nThe release gate runs `python scripts/compliance.py` against UpToCode's production Python\nsource. The current verified result is zero findings, zero suppressions, and zero unexplained\nanalysis warnings. Deliberately bad fixtures and synthetic redaction sentinels remain test\nevidence and are excluded from that production claim. This dogfood check is part of every\nrelease candidate, alongside the full offline suite and branch-coverage floor.\n\n## Built with Codex and GPT-5.6\n\nCodex was the development collaborator throughout UpToCode: it translated the product\nspecification into vertical slices, implemented and reviewed the scanner, CLI, reports,\nMCP servers, site, and tests, fixed clean-clone defects, and ran the Windows/POSIX\nsubmission gates. UpToCode also produces a report-bound `FIXPLAN.md` with a copy-paste\nCodex hand-off, so approval—not automatic source mutation—connects analysis to coding.\nThe competition-first work order, decisions, progress log, and validation report remain\nin the repository as an auditable record of that collaboration.\n\nGPT-5.6 powers the optional judgment tier through OpenAI Responses Structured Outputs.\nIt evaluates only bounded, redacted evidence for candidate rules that need contextual\njudgment. The feature is opt-in twice (`--judgment --send-code`), uses `store=false`, and\nnever replaces or deletes deterministic static findings when a request fails or is\nrefused. Ordinary tests, the judge test build, and the demo dry-run are entirely offline;\nany live paid call requires separate operator approval.\n\n## Project evidence\n\n- [Implementation specification](SPEC.md)\n- [Goal prompt](GOAL.md)\n- [Progress and self-scan triage](PROGRESS.md)\n- [Validation report](tasks/validation-report.md)\n- [Architecture compliance matrix](docs/architecture-compliance.md)\n- [Reference production specification](specs/002-reference-production.md)\n- [Hosted operations and rollback](docs/operations.md)\n- [Hosted judge access](docs/hosted-judge-access.md)\n- [Under-three-minute demo script](docs/demo-script.md)\n- [Event rules and evidence checklist](docs/event-rules.md)\n- [Submission evidence index](docs/submission-evidence/README.md)\n\nNo repository, package, video, deployment, or submission is published by this project workflow without explicit approval.\n",
  "bytes": 20812,
  "sha": "645a7b504594a64f15d1a214ae71a714f5b038b2b7c7c8a6468e11e26c338591",
  "repo_slug": "ddyrich72/uptocode",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ddyrich72_uptocode_e09dedd2/readme"
}