sysndd-mcp-readonly

Estrellas6

Forks0

Actualizado6 de julio de 2026 a las 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

Instalación

Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.

Fuente

berntpopp

berntpopp/sysndd

Abrir repositorio de GitHub Ver repositorios del creador

Descarga

Ocupaciones relacionadasSOC

Basado en la clasificación ocupacional SOC

Desarrolladores de softwareOcupaciones informáticas y matemáticas·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

Más de este repositorio

mismo repositorio

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