SHD MCP Plugin

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/shd/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 read-only dashboard with:

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

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 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.

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
sha256sum --check plugins/shd-mcp-plugin/widgets/active-projects/v1/SHA256SUMS

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.

5.4 KiB Raw Blame History