Public installable plugin package for SHD project workflows. It combines Codex Skills with the authenticated SHD MCP server and keeps business logic, ACLs, OAuth and persisted data in SHD itself.

What the user installs

The package contains:

.codex-plugin/plugin.json — plugin metadata;
.mcp.json — the official SHD Streamable HTTP MCP endpoint;
skills/ — routing, project, ProjectBase, task, file, finance, CRM, analytics, estimates, scheduling, entity resolution, Wiki, discussions, documents, organizations/ACL, notifications, inventory, agents, status-page, realtime/activity, Terms/contracts and Gitea workflows;
assets/ — plugin branding;
widgets/ — versioned MCP Apps resources with manifest, checksum and provenance metadata;
.agents/plugins/marketplace.json — a ready local marketplace entry.

It does not contain the SHD Laravel application, database code or credentials.

Install in Codex

Clone this repository and register its marketplace:

git clone https://github.com/bulava92/shd-mcp-plugin.git
cd shd-mcp-plugin
codex plugin marketplace add "$PWD"
codex plugin add shd-mcp-plugin@shd-public

The same commands work with the Gitea clone URL:

git clone https://git.xyz.su/markkats/shd-mcp-plugin.git

After installation, start a new Codex thread so the plugin Skills are loaded.

ChatGPT custom app

ChatGPT uses the same SHD MCP server connection, but it is added separately in the ChatGPT account: open Settings → Apps/Connectors → Developer mode, create a custom app and set the MCP URL to https://shd.xyz.su/mcp. Complete the SHD OAuth flow and refresh the app after server metadata changes.

The active-projects result can render an inline MCP Apps widget. It is a small dashboard with:

Проект → Дата завершения → Статус;
sorting by the nearest deadline;
local search by project name/code;
a refresh action, a project-details panel and controlled project actions.

If the host does not support MCP Apps UI, the data tool and the plain Markdown table remain fully usable.

The backend serves the checked-in widget artifact at ui://shd/active-projects/v1.html; its manifest and SHA256SUMS are kept next to the HTML resource under plugins/shd-mcp-plugin/widgets/active-projects/v1/.

The same data/render contract is available for Documents, Tasks, Finance, CRM, Discussions, Notifications, Scheduling, Inventory, Agents, Status Page, Project DB, Notes, Project overview, Files, Proposals, Terms, Activity, Organizations and access, Gitea Issues and Schemes:

shd_render_documents_widget → ui://shd/documents/v1.html;
shd_render_tasks_widget → ui://shd/tasks/v1.html;
shd_render_finance_widget → ui://shd/finance/v1.html;
shd_render_crm_widget → ui://shd/crm/v1.html;
shd_render_discussions_widget → ui://shd/discussions/v1.html;
shd_render_notifications_widget → ui://shd/notifications/v1.html;
shd_render_scheduling_widget → ui://shd/scheduling/v1.html;
shd_render_inventory_widget → ui://shd/inventory/v1.html;
shd_render_agents_widget → ui://shd/agents/v1.html;
shd_render_status_page_widget → ui://shd/status-page/v1.html;
shd_render_project_db_widget → ui://shd/project-db/v1.html;
shd_render_notes_widget → ui://shd/notes/v1.html.
shd_render_project_overview_widget → ui://shd/project-overview/v1.html;
shd_render_files_widget → ui://shd/files/v1.html;
shd_render_proposals_widget → ui://shd/proposals/v1.html;
shd_render_terms_widget → ui://shd/terms/v1.html;
shd_render_activity_widget → ui://shd/activity/v1.html;
shd_render_organizations_widget → ui://shd/organizations/v1.html;
shd_render_gitea_widget → ui://shd/gitea/v1.html;
shd_render_schemes_widget → ui://shd/schemes/v1.html;
shd_render_task_kanban_widget → ui://shd/task-kanban/v1.html;
shd_render_team_workload_widget → ui://shd/team-workload/v1.html;
shd_render_project_timeline_widget → ui://shd/project-timeline/v1.html;
shd_render_crm_funnel_widget → ui://shd/crm-funnel/v1.html;
shd_render_finance_dashboard_widget → ui://shd/finance-dashboard/v1.html;
shd_render_proposal_approvals_widget → ui://shd/proposal-approvals/v1.html;
shd_render_documents_completeness_widget → ui://shd/documents-completeness/v1.html;
shd_render_agents_health_widget → ui://shd/agents-health/v1.html;
shd_render_schedule_calendar_widget → ui://shd/schedule-calendar/v1.html;
shd_render_acl_matrix_widget → ui://shd/acl-matrix/v1.html;
shd_render_inventory_warnings_widget → ui://shd/inventory-warnings/v1.html;
shd_render_gitea_board_widget → ui://shd/gitea-board/v1.html;
shd_render_schemes_progress_widget → ui://shd/schemes-progress/v1.html;
shd_render_notes_tree_widget → ui://shd/notes-tree/v1.html;
shd_render_project_db_preview_widget → ui://shd/project-db-preview/v1.html.

Each widget accepts normalized records from its list tool, keeps the plain structured response as a fallback and uses the MCP Apps bridge before the window.openai compatibility API.

The official OpenAI directory is optional. It is useful for public discovery, one-click installation and review of a public app; it is not required for an internal team or a manually added ChatGPT custom app. See the official MCP server guide, UI guide, and submission guide when public listing is the goal.

Connect SHD

Installation and authorization are separate steps:

The client reads .mcp.json and opens the SHD OAuth flow.
The user signs in to SHD and approves the requested MCP connection.
SHD issues the client an authorization; the client stores it securely.
Every tool call is checked again by SHD for organization, project and module permissions.

The user does not need to put a token in this repository. A personal access token may be used only if the selected MCP client and SHD deployment explicitly support it; enter it in that client's secure connection settings, never in .mcp.json, Skills or an issue.

SHD OAuth supports ChatGPT CIMD clients with PKCE S256 and private_key_jwt client authentication. The server validates the client assertion against ChatGPT's published JWKS; the plugin package never stores the assertion, access token or refresh token.

For ChatGPT or another MCP client without Codex plugin installation, add the same HTTPS endpoint as a custom MCP app and complete OAuth there. The public repository packages the workflows; it does not grant access to the server.

Troubleshooting

Plugin installs but tools are unavailable: reconnect SHD OAuth and start a new thread.
Projects are missing: the SHD account or organization lacks access, or the project is archived; verify permissions in SHD.
A write is rejected: the server ACL, required role, version or conflict check rejected it. Do not bypass the error with a different token.
A module is not covered by a dedicated skill: use shd-routing; the MCP server still exposes the current authenticated tool catalog, while skills provide focused workflow and safety guidance for common module operations.
Another SHD installation is required: use its approved MCP URL and its OAuth resource in the client's secure connection configuration.

Local validation

From the repository root:

python3 -m unittest discover -s tests -v
python3 scripts/check_skill_mcp_parity.py --strict
for checksum in plugins/shd-mcp-plugin/widgets/*/v1/SHA256SUMS; do
  (cd "$(dirname "$checksum")" && sha256sum --check SHA256SUMS)
done

Refresh the catalog snapshot after a backend MCP catalog change:

node /var/www/admin/scripts/mcp/mcp-catalog.mjs | \
  python3 scripts/update_mcp_tool_catalog.py

The runtime smoke harness checks OAuth metadata, PKCE S256 support, the authenticated MCP handshake and all thirty-six widget resources. It never assumes an endpoint or prints a token:

SHD_MCP_RUNTIME_URL=https://approved-host.example/mcp \
SHD_MCP_ACCESS_TOKEN="$TOKEN" \
node scripts/mcp-runtime-smoke.mjs --require-auth

For a full authorization-code/PKCE browser check, provide an already authenticated Playwright storage state and the client redirect registered with SHD:

SHD_MCP_RUNTIME_URL=https://approved-host.example/mcp \
SHD_OAUTH_E2E_STORAGE_STATE=/secure/oauth-state.json \
SHD_OAUTH_E2E_CLIENT_ID="$OAUTH_CLIENT_ID" \
SHD_OAUTH_E2E_REDIRECT_URI="$OAUTH_REDIRECT_URI" \
node scripts/mcp-oauth-e2e.mjs

The browser/OAuth checks are opt-in deployment checks and are not run in the public static-package workflow.

The full release boundary, including backend deployment and authenticated ChatGPT/browser checks, is documented in RELEASE.md.

Development

Keep changes inside the plugin package. Do not copy backend implementation into Skills. Each workflow should use the narrowest existing SHD MCP tool, read before write, require explicit confirmation for mutations and report missing data instead of inventing it.

Before publishing a release, validate the plugin package with the Codex plugin validator and separately verify OAuth and MCP runtime behavior against the approved deployment. A static package check is not runtime proof.

License

The repository is public source, but the plugin and SHD branding are distributed under the proprietary SHD MCP Plugin License. Public visibility does not grant rights to redistribute, resell, modify or reuse the package outside the permitted SHD use.