86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
1. The client reads `.mcp.json` and opens the SHD OAuth flow.
|
|
2. The user signs in to SHD and approves the requested MCP connection.
|
|
3. SHD issues the client an authorization; the client stores it securely.
|
|
4. 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](LICENSE). Public visibility does
|
|
not grant rights to redistribute, resell, modify or reuse the package outside
|
|
the permitted SHD use.
|