shd-modules-mcp-plugin/plugins/shd-mcp-plugin/README.md

SHD MCP plugin package

This directory is the installable Codex plugin. It packages reusable SHD workflow Skills and the official SHD MCP connection; it does not contain the SHD backend or a second MCP server.

The plugin requires an SHD account authorized for the requested projects and modules. Skills do not grant permissions or bypass server-side ACLs. Each Skill declares its module scope; the MCP server filters Skill discovery and Skill resources by the authenticated module access in the same way as prompts and data resources.

Use shd_prompt_search and shd_prompt_get for reusable workflow instructions, and shd_resources_search and shd_resources_get for current read-only context when the connected server exposes those helper tools. If a helper is missing, use the host's native MCP prompt or resource catalog and read methods when available. Tools perform operations; prompts guide multi-step work; resources return addressable context. All three remain subject to the authenticated SHD scope.

Included workflows

• active projects with completion dates and statuses;
• project status and risk summaries;
• ProjectBase schema and data-quality audits;
• AirBase record workflows, saved dashboards, AI-field preview/runs and registered Omni actions;
• guarded task workflows;
• project file inspection and actions;
• scoped Knowledge entries, context, drafts and review;
• allowlisted source, database and service editing with guarded writes;
• read-only inspection of allowlisted source repositories;
• Zulip streams, topics, messages, search and explicit message actions;
• Grafana dashboards, data sources, metrics, logs, alerts and incidents;
• SHD administration settings, users, organizations and access audits;
• finance and CRM read/audit workflows;
• finance account, balance, payment and settlement audits;
• analytics, comparisons, reports and task/proposal metrics;
• entity resolution and duplicate-candidate analysis;
• estimates, proposals and estimate-document-contract workflows;
• scheduling events, slots and booking positions;
• Wiki, notes, revisions and note-database workflows;
• discussions, channels, topics, messages and attachments;
• documents, templates, PDFs, revisions and public-link workflows;
• organizations, members, invitations, ACL and two-factor policies;
• notifications, preferences and read-state workflows;
• inventory, assets, stock, procurement and stocktake workflows;
• service catalog, version, approval and site-publication workflows;
• short-link, public-alias, rotation and revocation workflows;
• authenticated profile workflows;
• agent/controller diagnostics, tunnels, endpoints and runtime actions;
• PDF Scheme Editor plan geometry, including focused room tracing and wall, window and door tracing around wall faces, thresholds, columns, boxes, niches and openings, plus annotations, calibration and lighting-layer workflows;
• status-page monitors, groups, history and incidents;
• realtime sessions, event cursors and operational activity;
• Terms documents, revisions, completeness and contract discussions;
• linked Gitea issues, labels, comments and attachments;
• safe bulk-change planning and validation rules.

The legacy System Base workflow is not included: the current MCP registration does not publish a System Base module or its tools.

When the connected MCP host supports MCP Apps UI, the 44 SHD render tools have inline interactive widgets: active projects, module registers and specialized Kanban, workload, timeline, funnel, dashboard, calendar, matrix, tree and Project DB views. Each widget sorts or filters normalized records, shows status/value fields, can load one selected record’s details where supported and exposes only the write actions declared by its render metadata. A write always requires an explicit form submission; destructive actions also require a confirmation checkbox. After a successful mutation, the widget refreshes its source list. The same tools still return normal structured data for hosts that do not render widgets.

The controller observability render tools share the versioned widgets/controller-observability/v1/ resource. It exposes controller device inventory and profiles, normalized live states, server-computed binary/numeric statistics, explicit native vs Influx/Grafana provenance, universal comparison presets, complete controller topology, telemetry health and operation audit. Expert-setting controls are enabled only for source-provided writable descriptors.

The active-projects source is widgets/active-projects/source.html with its resource metadata in widgets/active-projects/widget.json. Before starting the backend, generate the ignored runtime files with:

node scripts/generate-widget-artifacts.mjs

The backend then reads the generated widgets/active-projects/v1/ artifact for the ui://shd/active-projects/v1.html resource.

The standard module resources are generated from the single widgets/_shared/universal-widget.html source by scripts/generate-widget-artifacts.mjs. Each generated artifact still keeps its own URI, manifest, SHA256 checksum and provenance note: this preserves resource cache keys and module-scope registration while removing duplicated HTML, bridge and action runtime code. The generator also injects the shared widgets/_shared/widget-theme.css and widgets/_shared/write-actions.css into the specialized active-projects and controller-observability renderers, so every widget uses the same spacing, surfaces, controls, tables and responsive rules without changing their data contracts. The generator supports --check for a no-write consistency check. Module copy and fallback tool configuration lives in the sibling widgets/_shared/universal-widget-config.json source and is injected into each universal standalone artifact by the generator. For an older template that still contains the inline configuration block, run --extract-config once and then --migrate-template once. The specialized applications remain separate only where their interaction contracts differ. Render tools are deliberately separate from list tools so data access and UI rendering remain auditable.

The generated widgets/*/v1/ directories are ignored and must not be committed. A fresh checkout or deployment must run the generator before the MCP backend starts; --check can then verify that the local runtime output is current.

MCP connection

The package points to https://shd.xyz.su/mcp and requests OAuth for that MCP resource. The client stores the resulting authorization; this repository never contains an access token.

If a client or SHD installation uses another official endpoint, change the connection in .mcp.json in that client's secure configuration. Do not commit tokens, cookies, client secrets or private host credentials.