128 lines
6.7 KiB
Markdown
128 lines
6.7 KiB
Markdown
# 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:
|
||
|
||
```sh
|
||
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.
|