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 and CRM workflows;
assets/ — plugin branding;
.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.

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.
Another SHD installation is required: use its approved MCP URL and its OAuth resource in the client's secure connection configuration.

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.

3.2 KiB Raw Blame History