02398258a5
- Add GET/POST /login to hermes for first-party cookie during OAuth popup (fixes browser CHIPS cookie partitioning that broke claude.ai connection) - Add role column to all findCustomer* SQL queries in src/auth.ts - Add claude.ai tab to docs/getting-started.html with OAuth flow steps - Add ARCHITECTURE.md with system diagrams, data flow, and key invariants - Rewrite README.md and DEPLOY.md to reflect actual MicroK8s deployment - Deploy updated docs site (squaremcp-docs sha256 updated) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
156 lines
4.0 KiB
Markdown
156 lines
4.0 KiB
Markdown
# Hermes MCP — SquareMCP Gateway
|
|
|
|
Hermes is the MCP server powering [SquareMCP](https://squaremcp.com). It exposes 51 tools across 11 platforms (email, Obsidian, WhatsApp, LinkedIn, TikTok, Facebook, Instagram, Twitter, Telegram, Discord, Snapchat) over Streamable HTTP, with per-user authentication, OAuth 2.0, and multi-tenant credential isolation.
|
|
|
|
**Production endpoint:**
|
|
```
|
|
https://hermes.squaremcp.com/mcp
|
|
```
|
|
|
|
---
|
|
|
|
## Quick connect
|
|
|
|
### claude.ai
|
|
1. Settings → MCP Servers → Add → enter `https://hermes.squaremcp.com`
|
|
2. Complete the OAuth popup (login with your SquareMCP credentials)
|
|
3. Click "Connect MCP client"
|
|
|
|
### Claude Desktop
|
|
```json
|
|
// ~/Library/Application Support/Claude/claude_desktop_config.json
|
|
{
|
|
"mcpServers": {
|
|
"squaremcp": {
|
|
"type": "http",
|
|
"url": "https://hermes.squaremcp.com/mcp",
|
|
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Codex CLI
|
|
```toml
|
|
# ~/.codex/config.toml
|
|
[mcp_servers.squaremcp]
|
|
url = "https://hermes.squaremcp.com/mcp"
|
|
headers = { Authorization = "Bearer YOUR_TOKEN" }
|
|
```
|
|
|
|
### opencode
|
|
```json
|
|
{
|
|
"mcp": {
|
|
"squaremcp": {
|
|
"type": "remote",
|
|
"url": "https://hermes.squaremcp.com/mcp",
|
|
"headers": { "x-api-key": "YOUR_API_KEY" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Get your token from the [SquareMCP dashboard](https://app.squaremcp.com) → Connect MCP Client.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full architecture with diagrams.
|
|
|
|
```
|
|
nginx ingress (TLS)
|
|
│
|
|
┌────────────┼────────────┐
|
|
│ │ │
|
|
hermes-mcp squaremcp-app squaremcp-docs
|
|
:3456 :8080 :80
|
|
(MCP API) (SaaS UI) (Docs)
|
|
│
|
|
┌─────────┼─────────┐
|
|
│ │ │
|
|
MySQL 8 Redis 7 /vaults
|
|
(creds + (cache + (Obsidian)
|
|
billing) DLQ)
|
|
```
|
|
|
|
**Stack:** TypeScript / Node.js, Express, MySQL 8, Redis 7, MicroK8s, Docker
|
|
**Auth:** JWT session cookies + OAuth 2.0 PKCE + API key
|
|
**Platform clients:** 11 platforms, 51 MCP tools
|
|
|
|
---
|
|
|
|
## Platforms
|
|
|
|
| Platform | Tools |
|
|
|----------|-------|
|
|
| Email (IMAP/SMTP) | search, read, send, draft, folders |
|
|
| Obsidian | search, read, append, update, sync |
|
|
| WhatsApp Business | send, template, list templates |
|
|
| LinkedIn | profile, post, search connections, message, video |
|
|
| TikTok | profile, creator info, upload video, status |
|
|
| Facebook | page, posts, post, photo, video |
|
|
| Instagram | profile, media, post, reel |
|
|
| Twitter/X | profile, tweets, search, tweet, video |
|
|
| Telegram | me, send, photo, updates, chat |
|
|
| Discord | me, guilds, channels, send, messages |
|
|
| Snapchat | me, ad accounts, create snap |
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
Hermes accepts (in priority order):
|
|
|
|
1. `x-api-key` header — global superadmin or per-customer key
|
|
2. `Authorization: Bearer <token>` — JWT or OAuth access token
|
|
3. `Cookie: session=<JWT>` — web session (set by `/api/auth/login` or `/login`)
|
|
|
|
---
|
|
|
|
## Transports
|
|
|
|
| Transport | URL |
|
|
|-----------|-----|
|
|
| Streamable HTTP (preferred) | `https://hermes.squaremcp.com/mcp` |
|
|
| Legacy SSE | `https://hermes.squaremcp.com/sse` |
|
|
|
|
---
|
|
|
|
## Client setup guides
|
|
|
|
- [Codex CLI](./CODEX_SETUP.md)
|
|
- [Claude Code / CLI agents](./AGENTS_CLI_SETUP.md)
|
|
- [opencode](./OPENCODE.md)
|
|
- [ChatGPT Custom GPT](./CHATGPT_SETUP.md)
|
|
- [Social publishing (TikTok / Facebook)](./SOCIAL_PUBLISHING_SETUP.md)
|
|
|
|
---
|
|
|
|
## Local development
|
|
|
|
```bash
|
|
npm install
|
|
cp .env.example .env # fill in credentials
|
|
npm run dev
|
|
curl http://localhost:3456/health
|
|
```
|
|
|
|
Server runs on port `3456` by default.
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
See [DEPLOY.md](./DEPLOY.md) for the full deployment runbook.
|
|
|
|
The short version:
|
|
```bash
|
|
npm run build
|
|
docker build -t localhost:32000/hermes-mcp:latest .
|
|
docker push localhost:32000/hermes-mcp:latest
|
|
# update sha256 digest in hermes-k8s.yaml
|
|
microk8s kubectl apply -f hermes-k8s.yaml
|
|
```
|