From ce6e6197311ed1c4d98c327be855bffbe8bb9408 Mon Sep 17 00:00:00 2001
From: bulava92 <96921934+bulava92@users.noreply.github.com>
Date: Mon, 24 Aug 2026 16:49:50 +0500
Subject: [PATCH] Initial SHD MCP plugin package

---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bbcbe41
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# 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.