panini-connector-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autoscreen (Panini)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# panini-connector-mcp
+
+**MCP server that lets AI coding agents (Claude Desktop, Cursor, Windsurf, Claude Code, etc.) install and verify the [panini-connector](https://www.npmjs.com/package/panini-connector) SDK on a customer's self-hosted site — end-to-end, without human copy-pasting.**
+
+Companion to the wizard at panini.autoscreen.ai — same code generation, same verify flow, exposed as MCP tools an agent can call.
+
+## What it does
+
+Exposes 4 tools over the Model Context Protocol:
+
+| Tool | What it does |
+|---|---|
+| `install_panini_connector` | Given `(language, framework, storage)`, returns the install command + files to write + env vars to set. Handles Next.js App/Pages, Express, FastAPI, Django, Flask. Storage: Supabase, Postgres, custom DB (MySQL/Mongo/etc.), or in-memory. |
+| `verify_panini_connector` | Fires all 4 signed HTTP ops (`ping` / `create_post` / `update_post` / `delete_post`) at the deployed URL. Returns per-op status + diagnostics. Cleans up its own smoke-test post. |
+| `generate_shared_secret` | Returns a cryptographically-random 32-byte hex secret for `SEO_CONNECTOR_SECRET`. |
+| `get_envelope_schema` | Returns the raw HTTP envelope contract Panini uses. For agents implementing custom handlers in languages the SDK doesn't cover (Laravel, Rails, Go, .NET, etc.). |
+
+## Install (one line per client)
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "panini-connector": {
+      "command": "npx",
+      "args": ["-y", "panini-connector-mcp"]
+    }
+  }
+}
+```
+
+**Windows note**: GUI apps don't inherit shell PATH. Use `cmd` as the command instead:
+```json
+{
+  "mcpServers": {
+    "panini-connector": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "panini-connector-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see 4 new tools available.
+
+### Cursor
+
+Settings → Cursor Settings → MCP → Add new MCP server:
+
+```json
+{
+  "mcpServers": {
+    "panini-connector": {
+      "command": "npx",
+      "args": ["-y", "panini-connector-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "panini-connector": {
+      "command": "npx",
+      "args": ["-y", "panini-connector-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add panini-connector -- npx -y panini-connector-mcp
+```
+
+## Example agent workflow
+
+Once registered, prompt your AI:
+
+> "Install the panini-connector on this Next.js site. It uses Supabase — the table is `blog_posts` and posts render at `/blog/[slug]`."
+
+The agent will:
+
+1. Call `install_panini_connector` with `language=node`, `framework=next_app`, `storage=supabase`, `existing_table=blog_posts`, `url_template=https://.../blog/{slug}`
+2. Read the returned `install_command` and run `npm install panini-connector` in your project
+3. Write `app/api/seo-connector/route.ts` with the returned file content
+4. Call `generate_shared_secret` and prompt you to add `SEO_CONNECTOR_SECRET=<value>` to your hosting env vars
+5. Prompt you to redeploy
+6. Once deployed, call `verify_panini_connector` with your URL + the secret
+7. Report the result: 4 green ✓s means the round-trip works and you're ready to paste URL+secret into the Panini dashboard
+
+## Tool reference
+
+### `install_panini_connector`
+
+```typescript
+Input:
+  language: 'node' | 'python'
+  framework: 'next_app' | 'next_pages' | 'express' | 'fastapi' | 'django' | 'flask'
+  storage: 'supabase' | 'postgres' | 'custom_db' | 'memory'
+  existing_table?: string           // default 'blog_posts'
+  url_template?: string             // default 'https://yoursite.com/blog/{slug}'
+
+Output:
+  install_command: string           // shell command to run in project root
+  files: [{ path, content, language }]  // files the agent writes
+  env_vars: string                  // env vars to set on hosting
+  post_install_note?: string        // gotchas (bodyParser: false, etc.)
+  verify_command: string            // manual CLI verification command
+```
+
+Framework/language pairing:
+- `node` → `next_app` | `next_pages` | `express`
+- `python` → `fastapi` | `django` | `flask`
+
+### `verify_panini_connector`
+
+```typescript
+Input:
+  url: string                       // https://mysite.com/api/seo-connector
+  secret: string                    // exact SEO_CONNECTOR_SECRET value
+  timeout_ms?: number               // default 10000
+
+Output:
+  ok: boolean
+  url: string
+  ops: [{
+    op: 'ping' | 'create_post' | 'update_post' | 'delete_post'
+    status: 'pass' | 'fail'
+    http_status?: number
+    response_body?: unknown
+    error?: string
+  }]
+  summary: string
+```
+
+### `generate_shared_secret`
+
+```typescript
+Input: {}
+Output: { secret: string, length_bytes: 32 }
+```
+
+### `get_envelope_schema`
+
+```typescript
+Input: {}
+Output: {
+  http_method: 'POST'
+  request_headers: { ... }
+  request_body_shape: { ... }
+  response_success: { ... }
+  response_ping: { ... }
+  response_errors: { ... }
+  replay_window_seconds: 300
+  hmac_pseudocode: string
+  laravel_example: string
+}
+```
+
+Use this when the customer's stack isn't Node or Python — the returned contract is enough for an agent to hand-implement the connector in any language.
+
+## Running locally / debugging
+
+```bash
+# Test the server directly (JSON-RPC over stdio)
+npx panini-connector-mcp
+# then type an MCP initialize request; server responds on stdout, logs on stderr
+
+# Or with the MCP inspector
+npx @modelcontextprotocol/inspector npx panini-connector-mcp
+```
+
+## License
+
+MIT.