sysndd-mcp-readonly

Stars6

Forks0

UpdatedJuly 6, 2026 at 14:32

Use when changing the SysNDD read-only MCP sidecar, its tools, repositories, resources, capabilities, schema version, or anything the MCP layer reads or exposes — especially when a product requirement would have MCP write, generate, fetch externally, or surface non-public data

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

berntpopp

berntpopp/sysndd

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	sysndd-mcp-readonly
description	Use when changing the SysNDD read-only MCP sidecar, its tools, repositories, resources, capabilities, schema version, or anything the MCP layer reads or exposes — especially when a product requirement would have MCP write, generate, fetch externally, or surface non-public data

SysNDD MCP Read-Only Contract

Use this skill before changing the MCP sidecar (api/start_sysndd_mcp.R, api/services/mcp-*.R, api/functions/mcp-*.R). MCP v1 is a separate, read-only process serving approved public data only. The contract is safety-critical: violating it can leak curation-in-progress or misrepresent data to LLM clients.

Hard Invariants — MCP MUST NOT

Write the DB, call write routes, or execute raw SQL / raw R.
Call Gemini or any LLM generation. Summaries are cache-hit-only, admin-generated reads (require_validated = TRUE).
Call live external gene providers. Stored external IDs may be shown only as external_reference_identifier.
Expose draft reviews, re-review workflows, admin/user/log/job data, curation comments, or broad export payloads.

When a product ask conflicts with these (e.g. "include the latest review even if unapproved", "generate a summary on cache miss", "present NDDScore as the authoritative classification"), the invariant wins. Implement the compliant framing and push the extra need to the authenticated main API (Curator+) or an admin/worker job — never into MCP.

Approved-Public Enforcement

Repository queries must return only approved public data:

Active records from ndd_entity_view.
Review-derived synopsis / phenotype / variation / publication data only from primary approved reviews: is_primary = 1 AND review_approved = 1. Do not drop these gates to serve "fresher" content.

Cache Access Is Read-Only

The sidecar binds the same memoised wrapper names as the API and mounts api_cache read-only. It must not initialize cache versions, clear cache files, compute STRING/phenotype clusters, or write entries. Phenotype correlations are cache-hit-only — never call generate_phenotype_correlations() on a miss. A fingerprint mismatch may only make MCP miss, never serve stale (that is why the exp+db artifact is mounted read-only to MCP).

Adding or Changing a Tool

Build it as a thin composition of existing read-only repo helpers (see get_gene_research_context for the pattern). Register in mcp-tool-registry.R; wrap execution in mcp_tool_safe(...).
Label every payload's data_class: curated_sysndd_evidence, curated_derived_analysis, ml_prediction, llm_generated_summary, external_reference_identifier, or operational_metadata. NDDScore is always ml_prediction, not_evidence_tier, and never alters curated classifications.
Recoverable validation failures return a JSON tool result with schema_version, error.code, and isError = true — not a raw R error or JSON-RPC -32603.
Large tools default response_mode = "compact" and expose budget metadata; keep schema_version at the outer envelope only.
MCP_SCHEMA_VERSION (currently 1.2) is the compatibility contract — bump additively for a new tool, and keep get_sysndd_capabilities, resources/list, and resources/read aligned. Prompts are off by default (MCP_ENABLE_PROMPTS); enable only for intentional slash-command prompts.

Verify

Healthcheck stays cheap and data-independent: api/scripts/mcp-healthcheck.R (initialize + tools/list). The heavier api/scripts/mcp-smoke.R exercises real tools for dev/CI.
Guard tests: api/tests/testthat/test-mcp-*.R (repository, analysis service, publication-context-verified). A new tool needs a unit test asserting approved-only reads and correct data_class labels.

Common Mistakes

Mistake	Why it's wrong
Query drops `review_approved = 1` for freshness	Leaks draft/in-progress curation
Generate an LLM summary on cache miss	MCP has no egress/creds and must not write cache; generation is admin/worker-only
Present NDDScore as the evidence verdict	NDDScore is `ml_prediction`, not an evidence tier
Return raw R error on bad input	Clients expect the recoverable JSON error envelope
Add a tool without bumping `MCP_SCHEMA_VERSION` / updating capabilities	Breaks the discovery + compatibility contract

More from this repository

same repository

sysndd-external-proxy

berntpopp/sysndd

Use when adding or changing an external HTTP provider call in SysNDD (gnomAD, Ensembl, UniProt, AlphaFold, MGI, RGD, PubMed, PubTator, MONDO, JAX/HPO) or touching external-call timeouts, retries, caching, or per-request time budgets

2026-07-066

sysndd-frontend-integration

berntpopp/sysndd

Use when wiring a SysNDD Vue 3 view or component to the backend API, adding a typed API client, handling API errors, or binding backend data into BootstrapVueNext tables and tooltips — especially around Plumber response shapes and BVN table/tooltip quirks

2026-07-066

sysndd-migrations-db

berntpopp/sysndd

Use when adding or changing a SysNDD DB migration, editing a SQL view (especially ndd_entity_view or the core read views), touching the migration runner or manifest, restoring a database, or diagnosing a startup failure related to migrations

2026-07-066

sysndd-security-bug-scan

berntpopp/sysndd

Use when reviewing or writing SysNDD code for security vulnerabilities or correctness bugs — authorization/role gates, SQL/expression injection, credential and secret handling, data exposure through public or MCP surfaces, resource-exhaustion/DoS from external calls, error/info leakage, and the repo's known R/Plumber footguns — especially before merging a diff or PR

2026-07-066

sysndd-analysis-snapshots

berntpopp/sysndd

Use when changing gene clustering (STRING/Leiden functional axis or phenotype MCA/HCPC), the analysis snapshot builder or validator, the memoised clustering cache, cache coherence, or LLM cluster summaries — or deploying a clustering change so public endpoints and summaries reflect it

2026-07-066

sysndd-api-testing

berntpopp/sysndd

Use when writing, running, or fixing SysNDD R/Plumber API tests (testthat) — including database-writing tests, running a single test inside the API container, mocking external providers, or diagnosing SKIP-vs-PASS, helper-loading, or path-resolution issues

2026-07-066

name	sysndd-mcp-readonly
description	Use when changing the SysNDD read-only MCP sidecar, its tools, repositories, resources, capabilities, schema version, or anything the MCP layer reads or exposes — especially when a product requirement would have MCP write, generate, fetch externally, or surface non-public data

SysNDD MCP Read-Only Contract

Hard Invariants — MCP MUST NOT

Write the DB, call write routes, or execute raw SQL / raw R.
Call Gemini or any LLM generation. Summaries are cache-hit-only, admin-generated reads (require_validated = TRUE).
Call live external gene providers. Stored external IDs may be shown only as external_reference_identifier.
Expose draft reviews, re-review workflows, admin/user/log/job data, curation comments, or broad export payloads.

Approved-Public Enforcement

Repository queries must return only approved public data:

Active records from ndd_entity_view.
Review-derived synopsis / phenotype / variation / publication data only from primary approved reviews: is_primary = 1 AND review_approved = 1. Do not drop these gates to serve "fresher" content.

Cache Access Is Read-Only

Adding or Changing a Tool

Build it as a thin composition of existing read-only repo helpers (see get_gene_research_context for the pattern). Register in mcp-tool-registry.R; wrap execution in mcp_tool_safe(...).
Label every payload's data_class: curated_sysndd_evidence, curated_derived_analysis, ml_prediction, llm_generated_summary, external_reference_identifier, or operational_metadata. NDDScore is always ml_prediction, not_evidence_tier, and never alters curated classifications.
Recoverable validation failures return a JSON tool result with schema_version, error.code, and isError = true — not a raw R error or JSON-RPC -32603.
Large tools default response_mode = "compact" and expose budget metadata; keep schema_version at the outer envelope only.
MCP_SCHEMA_VERSION (currently 1.2) is the compatibility contract — bump additively for a new tool, and keep get_sysndd_capabilities, resources/list, and resources/read aligned. Prompts are off by default (MCP_ENABLE_PROMPTS); enable only for intentional slash-command prompts.

Verify

Healthcheck stays cheap and data-independent: api/scripts/mcp-healthcheck.R (initialize + tools/list). The heavier api/scripts/mcp-smoke.R exercises real tools for dev/CI.
Guard tests: api/tests/testthat/test-mcp-*.R (repository, analysis service, publication-context-verified). A new tool needs a unit test asserting approved-only reads and correct data_class labels.

Common Mistakes

Mistake	Why it's wrong
Query drops `review_approved = 1` for freshness	Leaks draft/in-progress curation
Generate an LLM summary on cache miss	MCP has no egress/creds and must not write cache; generation is admin/worker-only
Present NDDScore as the evidence verdict	NDDScore is `ml_prediction`, not an evidence tier
Return raw R error on bad input	Clients expect the recoverable JSON error envelope
Add a tool without bumping `MCP_SCHEMA_VERSION` / updating capabilities	Breaks the discovery + compatibility contract