Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
f04807d
feat: add stateless MCP HTTP app
Ma1kovich Jul 15, 2026
6ec73e8
refactor: harden MCP HTTP lifecycle
Ma1kovich Jul 15, 2026
52d7475
fix: make MCP lifecycle tests clean-checkout safe
Ma1kovich Jul 15, 2026
b88730b
feat: expose complete Starfetch guidance over MCP
Ma1kovich Jul 15, 2026
ce1e0d3
test: simplify MCP guidance coverage
Ma1kovich Jul 15, 2026
9422e43
Update AGENTS.md
Ma1kovich Jul 15, 2026
d52ae09
feat(mcp-app): add bounded table presentation contract
Ma1kovich Jul 15, 2026
8546474
feat(mcp-app): define bounded table presentation
Ma1kovich Jul 15, 2026
de9eb51
feat(mcp-app): add portable results table widget
Ma1kovich Jul 16, 2026
74e9f3d
Build and attest MCP app container
Ma1kovich Jul 16, 2026
b3321b0
Publish staging candidate images from project branch
Ma1kovich Jul 16, 2026
dab704c
Record candidate image metadata
Ma1kovich Jul 16, 2026
14117bb
Trim image publishing documentation
Ma1kovich Jul 16, 2026
9690af8
Clarify CI matrix job names
Ma1kovich Jul 16, 2026
e1853a1
Limit image publishing to container inputs
Ma1kovich Jul 16, 2026
5303586
Harden hosted MCP TAP access (STA-12)
Ma1kovich Jul 16, 2026
0ed5824
Publish latest staging candidate image (STA-20)
Ma1kovich Jul 16, 2026
bf5c266
Use Cloud Run-safe health endpoint
Ma1kovich Jul 16, 2026
d934536
Update README.md
Ma1kovich Jul 17, 2026
9158543
Correct MCP tool annotations (STA-30)
Ma1kovich Jul 17, 2026
261037c
Merge branch 'main' into project/starfetch-mcp-app
Ma1kovich Jul 17, 2026
c33c4f1
Document remote MCP service policies (STA-31)
Ma1kovich Jul 17, 2026
4e032d4
docs: clarify remote MCP policies and access
Ma1kovich Jul 17, 2026
30fcbd4
feat(mcp-app): prepare production origin and challenge
Ma1kovich Jul 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
.git
.github
.tmp
**/dist
**/node_modules
**/test-results
coverage
node_modules
npm-debug.log*
13 changes: 13 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ on:

jobs:
test:
name: Quality checks · Node.js ${{ matrix.node-version }}
runs-on: ubuntu-latest
strategy:
matrix:
Expand Down Expand Up @@ -50,3 +51,15 @@ jobs:
fail_ci_if_error: true
files: ./coverage/lcov.info
use_oidc: true

mcp-app-browser:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
node-version: 24
cache: npm
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npm --workspace @starfetch-js/mcp-app run test:browser
89 changes: 89 additions & 0 deletions .github/workflows/mcp-app-image.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
name: MCP App Image

on:
push:
branches:
- main
- project/starfetch-mcp-app
workflow_dispatch:

permissions:
artifact-metadata: write
contents: read
packages: write
attestations: write
id-token: write

env:
IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/starfetch-mcp-app

jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
node-version: 22.22.0
cache: npm
- run: npm ci
- run: npm --workspace @starfetch-js/mcp-app run check
- uses: docker/setup-buildx-action@v3
- run: npm run smoke:container
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- id: build
uses: docker/build-push-action@v6
with:
context: .
file: apps/mcp-app/Dockerfile
platforms: linux/amd64
push: true
provenance: false
sbom: true
tags: |
${{ env.IMAGE_NAME }}:sha-${{ github.sha }}
${{ github.ref == 'refs/heads/project/starfetch-mcp-app' && format('{0}:staging-candidate', env.IMAGE_NAME) || '' }}
cache-from: type=gha,scope=starfetch-mcp-app
cache-to: type=gha,mode=max,scope=starfetch-mcp-app
labels: |
org.opencontainers.image.revision=${{ github.sha }}
org.opencontainers.image.source=https://github.com/${{ github.repository }}
- name: Attest image provenance
uses: actions/attest@v4
with:
subject-name: ${{ env.IMAGE_NAME }}
subject-digest: ${{ steps.build.outputs.digest }}
push-to-registry: true
- name: Write immutable artifact manifest
env:
IMAGE_DIGEST: ${{ steps.build.outputs.digest }}
run: |
jq --null-input \
--arg image "$IMAGE_NAME" \
--arg digest "$IMAGE_DIGEST" \
--arg repository "$GITHUB_REPOSITORY" \
--arg sourceRef "$GITHUB_REF" \
--arg sourceSha "$GITHUB_SHA" \
--arg workflowRun "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" \
'{
architecture: "linux/amd64",
digest: $digest,
healthRoute: "/health",
image: $image,
mcpRoute: "/mcp",
node: "22.22.0",
port: 8080,
repository: $repository,
sourceRef: $sourceRef,
sourceSha: $sourceSha,
workflowRun: $workflowRun
}' > starfetch-mcp-app-artifact.json
- uses: actions/upload-artifact@v4
with:
name: starfetch-mcp-app-artifact-${{ github.sha }}
path: starfetch-mcp-app-artifact.json
if-no-files-found: error
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ node_modules/
dist/
build/
coverage/
playwright-report/
test-results/
.nyc_output/
.tmp/
.cache/
Expand Down
33 changes: 32 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ Keep the package boundaries tight:
parsing, output conversion, presets, registry discovery, async jobs, and
typed errors.
- `@starfetch-js/mcp` is a thin MCP adapter over `@starfetch-js/core`.
- `apps/mcp-app` is a private Streamable HTTP host that constructs a fresh
`@starfetch-js/mcp` server and transport for each request. It owns only HTTP
policy, request lifecycle, and process shutdown.
- `@starfetch-js/skill` owns packaged static skill files and install helpers.
- `starfetch` is the CLI package and should stay a thin caller over
`@starfetch-js/core` and `@starfetch-js/skill`.
Expand All @@ -41,6 +44,7 @@ The implementation is an npm workspace with TypeScript ESM packages:
- `packages/cli` is `starfetch`;
- `packages/mcp` is `@starfetch-js/mcp`;
- `packages/skill` is `@starfetch-js/skill`.
- `apps/mcp-app` is the private `@starfetch-js/mcp-app` development host.

Target Node.js `>=22` for runtime packages. The root workspace may require a
later Node 22 patch release when development tooling requires it. Preserve Bun
Expand Down Expand Up @@ -116,9 +120,30 @@ Codex session so the configured `starfetch-local` MCP server is restarted, then
test through the real surfaced tools such as `mcp__starfetch_local.*`. Do not
use ad hoc stdio harnesses as proof that Codex can use the local MCP server.

## Issue Value Gate

Before planning or implementing an issue, challenge whether it should exist in
its current form. A detailed tracker item is not evidence that its scope is
valuable.

After reading the issue and inspecting the relevant code, answer:

1. What unique failure, user problem, or operational risk does this prevent?
2. Is that risk already prevented by the architecture, tests, or another issue?
3. Will planned follow-up work immediately invalidate or duplicate this work?
4. Does the issue introduce a second source of truth or maintenance artifact?
5. What is the smallest alternative: implement, shrink, merge, defer, or cancel?

Apply the deletion test at the issue level: if the issue disappears, what
important behavior becomes unowned?

Lead every issue plan with one recommendation: `Proceed`, `Shrink`, `Merge`,
`Defer`, or `Cancel`. If the issue has no distinct durable value, recommend
against implementing it before producing an implementation plan.

## Development Workflow

Work issue-by-issue. Keep each change aligned with the active GitHub issue and
Work issue-by-issue. Keep each change aligned with the active tracker issue and
avoid using one issue to implement future roadmap items.

For implementation work:
Expand Down Expand Up @@ -154,6 +179,12 @@ npm --workspace packages/mcp run build
Use `npm --workspace packages/mcp run smoke` as a package binary sanity check
when release or packaging behavior is relevant.

For Streamable HTTP app changes, also run:

```sh
npm --workspace @starfetch-js/mcp-app run check
```

For skill package changes, run:

```sh
Expand Down
Loading
Loading