astrodynamics-mcp 0.1.0__tar.gz

astrodynamics_mcp-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default reviewer for everything in this repo.
+*   @djankov

astrodynamics_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,75 @@
+name: Bug
+description: Report a defect in astrodynamics-mcp.
+title: "<short summary>"
+labels: ["type:bug"]
+body:
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: Observed behavior. Include error messages, MCP error envelopes, and tracebacks verbatim.
+    validations:
+      required: true
+  - type: textarea
+    id: what_expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest snippet that triggers the bug. A tool name plus the arguments you called it with (or the natural-language prompt that produced the broken call) is ideal.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: server_version
+    attributes:
+      label: astrodynamics-mcp version
+      placeholder: "e.g. 0.1.0, or git sha"
+    validations:
+      required: true
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport
+      options:
+        - stdio
+        - http
+        - Both
+    validations:
+      required: true
+  - type: input
+    id: client
+    attributes:
+      label: MCP client
+      description: Which client surfaced the bug, and its version.
+      placeholder: "e.g. Claude Code 2.4.1, Cursor 0.45, raw Python script using `mcp` SDK"
+    validations:
+      required: true
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.12.3"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - Windows
+        - macOS
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Server stderr, MCP error payloads, client-side traces.
+      render: shell

astrodynamics_mcp-0.1.0/.github/ISSUE_TEMPLATE/client-compatibility.yml

@@ -0,0 +1,81 @@
+name: Client compatibility report
+description: Tell us how astrodynamics-mcp works (or doesn't) inside a specific MCP client.
+title: "<client name + version>: <one-line outcome>"
+labels: ["type:client-compatibility"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template to report on a specific MCP client's behaviour:
+        whether stdio / http transports work, whether tools are visible, whether
+        tool descriptions and units survive the round-trip, and any client-side
+        quirks. These reports populate the "supported clients" matrix in the
+        docs. Even a successful "everything works" report is welcome.
+  - type: input
+    id: client
+    attributes:
+      label: MCP client and version
+      placeholder: "e.g. Claude Code 2.4.1, Cursor 0.45, ChatGPT desktop 1.2024.345, custom LangGraph agent on mcp 1.27.0"
+    validations:
+      required: true
+  - type: input
+    id: server_version
+    attributes:
+      label: astrodynamics-mcp version
+      placeholder: "e.g. 0.1.0, or git sha"
+    validations:
+      required: true
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport used
+      options:
+        - stdio
+        - http (Streamable HTTP)
+        - http (SSE — deprecated, backward-compat only)
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - Windows
+        - macOS
+        - Other
+    validations:
+      required: true
+  - type: dropdown
+    id: outcome
+    attributes:
+      label: Overall outcome
+      options:
+        - "Works — tools visible, calls succeed, results render."
+        - "Partial — some tools or call patterns are broken."
+        - "Broken — server doesn't load, or no tools visible to the client."
+    validations:
+      required: true
+  - type: textarea
+    id: setup
+    attributes:
+      label: Setup
+      description: Paste the exact MCP server config block (with secrets redacted).
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: tools_observed
+    attributes:
+      label: Tools the client sees
+      description: List which of the v0.1 tools the client surfaces (or "all 8" / "none"). If the client doesn't surface a `tools/list`, paste the closest observable equivalent.
+  - type: textarea
+    id: tools_called
+    attributes:
+      label: Tools you actually called
+      description: One or two example tool calls you ran end-to-end. Include the natural-language prompt that triggered each.
+  - type: textarea
+    id: problems
+    attributes:
+      label: Problems observed
+      description: Quirks, edge cases, broken units, awkward error rendering, slow timeouts — anything that worked but felt wrong.

astrodynamics_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/orgs/astro-tools/discussions
+    about: Open a discussion for usage questions, ideas, or general chat. The astro-tools org runs a single shared discussions space — there is no per-repo discussions board.

astrodynamics_mcp-0.1.0/.github/ISSUE_TEMPLATE/tool-request.yml

@@ -0,0 +1,54 @@
+name: Tool request
+description: I want astrodynamics-mcp to compute X — does it fit?
+title: "<short summary of the X you want>"
+labels: ["type:tool-request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        astrodynamics-mcp wraps vetted upstream astrodynamics libraries (sgp4,
+        lamberthub, skyfield, astropy, …) so LLM clients can call them as tools.
+        Before filing, please skim `CONTRIBUTING.md` — the "Scope discipline"
+        section names the libraries we wrap and the orthogonal projects that
+        own neighbouring surfaces. If your need is squarely in one of those
+        adjacent projects, you'll get a faster answer there.
+  - type: textarea
+    id: what_i_want
+    attributes:
+      label: What you want to compute
+      description: One or two sentences. What's the natural-language question you'd ask an LLM client that should drop into a tool call?
+      placeholder: "e.g. 'For a TLE I provide, when is the next eclipse of the satellite by Earth?'"
+    validations:
+      required: true
+  - type: textarea
+    id: example_session
+    attributes:
+      label: Example session
+      description: How would you prompt an MCP-enabled client (Claude Code, Cursor, ChatGPT desktop, …) to invoke this? What inputs / units / outputs do you expect?
+      placeholder: |
+        > User: "When does Hubble enter eclipse during the next 7 days?"
+        > # LLM should call: eclipse_predict(tle=..., start=..., duration_days=7)
+        > # Expected output: list of {entry_utc, exit_utc, duration_s, type: umbra|penumbra}
+    validations:
+      required: true
+  - type: textarea
+    id: upstream_library
+    attributes:
+      label: Upstream library that could back this
+      description: Which existing Python library (or libraries) implements the computation? If unsure, say so — we'll dig.
+      placeholder: "e.g. skyfield has eclipse helpers via dark_twilight_day; astropy.coordinates.get_sun + custom shadow geometry."
+  - type: textarea
+    id: what_i_tried
+    attributes:
+      label: What you tried instead
+      description: Did you try to use an existing tool (poorly) or a different MCP server? What broke or felt wrong?
+  - type: dropdown
+    id: priority
+    attributes:
+      label: How important is this to you
+      options:
+        - "Blocker — I can't use astrodynamics-mcp for my work without it."
+        - "Strong wish — I have a workaround but it's awkward."
+        - "Nice to have — drop into the backlog and ship when convenient."
+    validations:
+      required: true

astrodynamics_mcp-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,35 @@
+<!--
+Thanks for contributing to astrodynamics-mcp. Keep PRs small and scoped to one issue.
+-->
+
+## Summary
+
+<!-- One or two sentences: what this PR changes and why. -->
+
+Closes #
+
+## Changes
+
+<!-- Short bullet list of the substantive changes. Omit trivia (formatting, imports). -->
+
+-
+
+## Tested with
+
+<!-- Tick what you ran locally. CI will re-run on both Ubuntu and Windows. -->
+
+- [ ] `pytest`
+- [ ] `ruff check`
+- [ ] `ruff format --check`
+- [ ] `mypy`
+- [ ] End-to-end smoke against an MCP client (if this PR touches a tool, transport, or schema)
+
+## Breaking changes
+
+<!-- "None" if none. Otherwise: what breaks, who is affected, migration notes. -->
+
+None.
+
+## Notes for reviewers
+
+<!-- Optional. Things to look at first, known rough edges, questions for the reviewer. -->

astrodynamics_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      # Ubuntu + Windows × 3 Python minors = 6 cells. macOS is deferred
+      # to v0.2 per the project charter.
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install project
+        run: uv sync --all-groups
+
+      - name: Run pytest
+        # `-m "integration or not integration"` overrides the default
+        # marker filter in pyproject.toml so CI runs both unit and
+        # integration suites in a single invocation.
+        run: uv run pytest -m "integration or not integration" --cov --cov-report=term-missing
+
+      - name: Enforce coverage gates
+        # Per CONTRIBUTING.md: 90% overall, 95% on the layers whose
+        # correctness the LLM consumer can't sanity-check (units,
+        # schemas, data adapters). Run only on Ubuntu / Python 3.12 to
+        # avoid platform-specific differences inflating misses.
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: |
+          uv run coverage report --fail-under=90
+          uv run coverage report --include='src/astrodynamics_mcp/units.py' --fail-under=95
+          uv run coverage report --include='src/astrodynamics_mcp/schemas/*' --fail-under=95
+          uv run coverage report --include='src/astrodynamics_mcp/data/*' --fail-under=95
+
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  typecheck:
+    name: typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run mypy
+
+  # Smoke-check that `pip install astrodynamics-mcp` (no extras, no dev group)
+  # imports cleanly and the console script resolves. Catches an extras-only
+  # dependency leaking into the default install path. The full test job above
+  # exercises every dev dep via the dev group; this is a small canary.
+  minimal-install:
+    name: minimal install smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install .
+      - run: python -c "import astrodynamics_mcp"
+      - run: astrodynamics-mcp --version

astrodynamics_mcp-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run mkdocs build --strict
+
+  deploy:
+    name: deploy
+    needs: build
+    if: |
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - run: uv run mkdocs gh-deploy --force --no-history

astrodynamics_mcp-0.1.0/.github/workflows/eval.yml

@@ -0,0 +1,159 @@
+name: Eval
+
+on:
+  # Manual-only for now while the gate is being shaken down. Once it
+  # passes consistently, add `push: branches: [main]` and a weekly
+  # cron so regressions surface without per-PR cost.
+  workflow_dispatch:
+    inputs:
+      tier:
+        description: "Optional tier filter (single_tool | sequential | planning). Empty runs the full suite."
+        required: false
+        default: ""
+        type: choice
+        options: ['', 'single_tool', 'sequential', 'planning']
+
+concurrency:
+  group: eval-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  eval:
+    name: eval
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      # `models: read` lets the workflow call api.github.com/inference
+      # via the auto-generated GITHUB_TOKEN.
+      models: read
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - run: uv sync --all-groups
+
+      - name: Probe GitHub Models auth
+        # Run a one-token call against the eval model before the full
+        # suite so any auth failure surfaces here as a clear HTTP status
+        # and error body, rather than buried inside the Inspect AI stack
+        # trace. Prefer the MODELS_PAT secret when present — on Free-plan
+        # orgs the workflow-issued GITHUB_TOKEN is an unreliable inference
+        # auth path (observed 403 and 429 without obvious cause). Use a
+        # personal-owned PAT with `Models: Read` for MODELS_PAT; org-owned
+        # PATs return 403 no_access from this endpoint regardless of
+        # granted permissions. See eval/README.md for provisioning.
+        #
+        # Retries with exponential backoff because GitHub's secondary
+        # anti-abuse rate limit returns 429 for ~5-30 min when the
+        # triggering account has been making many recent requests. The
+        # retry loop lets routine CI churn ride through it.
+        env:
+          MODELS_PAT: ${{ secrets.MODELS_PAT }}
+          WORKFLOW_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TOKEN="${MODELS_PAT:-$WORKFLOW_TOKEN}"
+          status=""
+          for delay in 0 30 60 120 180; do
+            [ "$delay" -gt 0 ] && { echo "Backing off ${delay}s before retry"; sleep "$delay"; }
+            status=$(curl -s -o /tmp/probe.json -w '%{http_code}' \
+              https://models.github.ai/inference/chat/completions \
+              -H "Authorization: Bearer $TOKEN" \
+              -H "Content-Type: application/json" \
+              -d '{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"PING"}],"max_tokens":2}')
+            echo "HTTP $status"
+            head -c 500 /tmp/probe.json; echo
+            case "$status" in
+              200) break ;;
+              429) continue ;;
+              *)   echo "Non-retriable status $status"; break ;;
+            esac
+          done
+          test "$status" = "200"
+
+      - name: Run eval suite
+        env:
+          # The openai-api/github/* provider in Inspect AI derives env vars
+          # from the segment after the slash; here `github` maps to GITHUB_*.
+          # MODELS_PAT (if set) overrides the workflow-issued GITHUB_TOKEN —
+          # see the probe step above for the rationale.
+          GITHUB_API_KEY: ${{ secrets.MODELS_PAT || secrets.GITHUB_TOKEN }}
+          GITHUB_BASE_URL: https://models.github.ai/inference
+        run: |
+          # Flags explained:
+          # * -M strict_tools=false : pydantic unions in our schemas use
+          #     anyOf + $ref, which OpenAI strict-mode tool-calling rejects.
+          # * --max-samples 3       : prompts processed concurrently. GH
+          #     Models Free-plan Low-tier (gpt-4.1-mini) caps concurrent
+          #     requests at 5; we sit 2 below the ceiling to absorb
+          #     multi-turn tool-call bursts within each sample.
+          # * --max-connections 4   : max in-flight HTTP requests across
+          #     all samples (covers retries + tool-call turns); 1 below
+          #     the 5-concurrent ceiling so a transient retry can fire
+          #     without hitting the cap.
+          # * --no-fail-on-error    : let every sample run to completion
+          #     even when others error. Errored samples count against
+          #     accuracy in eval/_ci_report.py (zero-scored), so the
+          #     gate still fails them; we just don't want to lose data
+          #     from in-flight samples being cancelled when an error
+          #     threshold trips. Inspect AI's default ('fail on any
+          #     error') is too aggressive for a survey gate.
+          if [ -n "${{ inputs.tier }}" ]; then
+            uv run inspect eval eval/tasks.py@astrodynamics_mcp_eval_subset \
+              -T tier="${{ inputs.tier }}" \
+              --model openai-api/github/openai/gpt-4.1-mini \
+              -M strict_tools=false \
+              --max-samples 3 \
+              --max-connections 4 \
+              --no-fail-on-error \
+              --temperature 0 \
+              --log-dir logs
+          else
+            uv run inspect eval eval/tasks.py@astrodynamics_mcp_eval \
+              --model openai-api/github/openai/gpt-4.1-mini \
+              -M strict_tools=false \
+              --max-samples 3 \
+              --max-connections 4 \
+              --no-fail-on-error \
+              --temperature 0 \
+              --log-dir logs
+          fi
+
+      - name: Upload Inspect log artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: inspect-eval-logs
+          path: logs/
+          retention-days: 14
+
+      - name: Generate report
+        id: report
+        if: always()
+        # `set +e` so we capture the exit code; the workflow fails on it
+        # in the dedicated step below so the report still lands in the
+        # run summary even when the gate fails. The report body is
+        # appended to GITHUB_STEP_SUMMARY — that's where the score
+        # appears at the top of the workflow run page.
+        run: |
+          set +e
+          uv run python eval/_ci_report.py \
+            --log-dir logs \
+            --threshold 0.80 >> "$GITHUB_STEP_SUMMARY"
+          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
+
+      - name: Enforce threshold
+        # The report step uses `set +e`, so we fail here based on its exit code.
+        # Code 0 = passed gate, 1 = below threshold, 2 = missing or empty log.
+        if: steps.report.outputs.exit_code != '0'
+        run: |
+          echo "Eval gate failed: _ci_report.py exited with ${{ steps.report.outputs.exit_code }}."
+          exit 1

astrodynamics_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/astrodynamics-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  github-release:
+    name: github release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes \
+            dist/*