Skip to content

Phase 5: MCP docs, OSA wiring, and release #1297

Closed

Description

@neuromechanist

Part of epic #1065. Companion PR in nemarOrg/docs adding an MCP section to the For-agents guide with client configurations for Claude Desktop, Cursor, and OSA. Companion PR in OpenScience-Collective/osa adding the mcp_servers URL to the NEMAR assistant config. Verify on mcp-test.nemar.org, then enable the production route, then check off the acceptance criteria in #1065.

Definition of done: mcp.nemar.org reachable over Streamable HTTP, listed on docs.nemar.org, and consumed by the OSA NEMAR assistant on staging.

Activity

  1. neuromechanist commented on Sep 8, 2026

    @neuromechanist
    ContributorAuthor

    Companion deliverable on the website side: nemarOrg/website#319 asks for /.well-known/mcp/server-card.json on nemar.org (SEP-1649) pointing at https://mcp.nemar.org/mcp, generated from the shared contract. Check it off from this phase's PR.

  2. neuromechanist commented on Sep 9, 2026

    @neuromechanist
    ContributorAuthor

    Phase 5 status: three of four parts landed, one in review.

    In-repo (nemar-cli) -- done. ADR 0050 and the Python verification script
    merged in #1330, plus the epic review's fixes and a CI lint gate for
    scripts/mcp/ in #1335. Released as v0.10.1, which provisioned
    mcp.nemar.org (a custom_domain route, so the hostname did not exist before the
    deploy).

    Verification -- done, and it reordered the phase. Staging came up first and
    every transport-level check passed against mcp-test.nemar.org: 2026-07-28
    negotiated from the official Python SDK, all six tools with their inputSchema,
    the tools/list cache hint, GET/DELETE 405, OPTIONS 204, a missing
    Mcp-Method 400, a disallowed Origin 403, describe_dataset end to end, and
    the D1 gate refusing a real private dataset (nm000103) with the same wording an
    unknown id gets.

    But zarr-test.nemar.org's catalog is count: 0 -- the dev environment has no
    converted dataset at all
    -- so the four recording-level tools had nothing to
    read there, and the docs examples this phase was supposed to copy from staging did
    not exist. Production has 625. Owner decision 2026-09-09: release first, then
    document from production. All six tools now verified against mcp.nemar.org.

    Docs -- done, nemarOrg/docs#27, live at
    docs.nemar.org/platform/for-agents.

    One correction to this issue's own premise, and it was in my favour: this issue
    said to add an MCP section to the For-agents guide, and an earlier note of mine
    claimed no such guide existed and a new page was needed. The issue was right and
    the note was wrong
    -- platform/for-agents.md has been published since
    2026-09-03, and I had read a stale local checkout instead of origin/main. It is
    a section on that page, as originally specified. Every request and response in it
    is copied from a real session against mcp.nemar.org.

    That PR also retargets four ADR 0025 links to ADR 0049, which supersedes it,
    and drops the "any future NEMAR tool server returns a recipe" framing from
    cost-ladder.md and index-contract.md: that server now exists, so those pages
    point at it.

    OSA -- in review, OpenScience-Collective/osa#352.

    Worth stating plainly because it changes what this part was: OSA's two NEMAR tools
    were already dead. Both called
    nemar.org/api/dataexplorer/datapipeline/..., which returns 404 since the legacy
    dataexplorer site was retired. So this replaces them rather than adding to them,
    and OSA had no MCP runtime at all -- mcp_servers existed in the config model with
    a "(Phase 2)" docstring and nothing read it.

    The one real design constraint: CommunityAssistant.__init__ is synchronous and
    FastAPI calls it from inside a running event loop, where asyncio.run raises. So
    discovery runs in a worker thread with its own loop. Mutation-checked: with a bare
    asyncio.run the running-loop test fails while the plain synchronous one passes.
    Tests stand up a real MCPServer over Streamable HTTP -- no mocks -- and a
    network-marked tier passes against mcp.nemar.org.

    Keeping this open until #352 merges. Epic #1065 is closed: all eight of its
    acceptance criteria are verified against production, with two deliberate deviations
    called out in its closeout comment.

  3. neuromechanist commented on Sep 10, 2026

    @neuromechanist
    ContributorAuthor

    Phase 5 complete. Definition of done, item by item:

    mcp.nemar.org reachable over Streamable HTTP. Released in v0.10.1. Verified against production with scripts/mcp/verify_streamable_http.py --url https://mcp.nemar.org/mcp (the official Python mcp 2.2.0 SDK): initialize, all six tools listed, one real call per tool, the provenance envelope present on each, and the over-cap read_window refusal returning a typed refusal rather than a truncated window. The multi-chunk render_overview path that phase 4 fixed was confirmed on real data: width_px: 800 selects level 3 and reads 3 chunks, returning an 800x1259 PNG.

    Listed on docs.nemar.org. nemarOrg/docs#27, merged and live: a ## Tool calling: mcp.nemar.org section on the For-agents guide, with the transport, the six tools, a real session trimmed from the production verification run, the recipe-versus-taste rule, the provenance envelope, the limits, and client configuration for Claude Desktop, Cursor and OSA. Every example is copied from a real session, none from the design doc.

    Consumed by the OSA NEMAR assistant. OpenScience-Collective/osa#352, merged: src/tools/mcp_client.py is a real MCP runtime (the repo had none), and the NEMAR assistant now gets its dataset tools from https://mcp.nemar.org/mcp instead of the two hand-written tools that called the retired dataexplorer endpoint and had been returning 404. Two follow-ups also merged: osa#354 pointed the assistant's documentation URL at nemar.org/discover (read from the website's own src/lib/host.ts, not guessed), and osa#355 fixed the documentation-URL check to send a named User-Agent, which had been misreporting a working third-party page as a 403.

    Proof from merged develop, not from the branch: the network-marked live tests pass against production (the six tool names are exactly the documented set, a search returns real datasets, a refusal arrives as readable text), and the documentation-URL check passes for all 16 communities.

    Two things this phase produced that were not in its plan:

    Epic #1065 is closed with all eight acceptance criteria checked and the two deviations recorded there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew feature or enhancement

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions