yuukiii/hermes-mcp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat: native OAuth login page, architecture docs, docs site update

Browse Source 
- 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>
This commit is contained in:
Garfield
2026-05-14 13:48:01 -04:00
parent 61dab40585
commit 02398258a5
13 changed files with 697 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
README.md
View File

@@ -1,108 +1,130 @@
# Hermes MCP
# Hermes MCP — SquareMCP Gateway
Hermes MCP is a hosted MCP gateway for messaging, knowledge, and social connectors.
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.
The production endpoint is:
```text
**Production endpoint:**
```
https://hermes.squaremcp.com/mcp
```
Hermes currently supports MCP access patterns for:
1. email
2. Obsidian vault notes
3. WhatsApp Business
4. LinkedIn
5. Telegram
6. additional social connectors that are in various states of credentialing and rollout
---
## What Hermes is for
## Quick connect
Hermes is the integration and connector layer behind broader product work such as SquareMCP.
Use Hermes when you want:
1. an MCP endpoint that exposes real tools over Streamable HTTP
2. API-key or OAuth-protected access
3. connector access from agent clients such as Codex CLI, Claude Code, opencode, or ChatGPT
---
## Core transports
| Transport | URL |
|----------|-----|
| Streamable HTTP (preferred) | `https://hermes.squaremcp.com/mcp` |
| Legacy SSE | `https://hermes.squaremcp.com/sse` |
---
## Authentication
Hermes accepts:
1. `x-api-key` header
2. `?key=` query parameter
3. `Authorization: Bearer ...` for OAuth-based clients
For local/manual config examples in this repo, always substitute your own value for:
```text
YOUR_MCP_API_KEY
```
Do not commit live API keys into repo config files.
---
## Client setup guides
Use the setup guide that matches your client:
1. [Codex CLI setup](./CODEX_SETUP.md)
2. [CLI agent setup (Claude Code, generic MCP CLIs, Claude Desktop)](./AGENTS_CLI_SETUP.md)
3. [opencode setup](./OPENCODE.md)
4. [ChatGPT Custom GPT setup](./CHATGPT_SETUP.md)
5. [Social publishing setup (TikTok / Facebook)](./SOCIAL_PUBLISHING_SETUP.md)
---
## Codex quick setup
Add this block to `~/.codex/config.toml`:
```toml
[mcp_servers.hermes]
url = "https://hermes.squaremcp.com/mcp"
```
See [CODEX_SETUP.md](./CODEX_SETUP.md) for the full notes and caveats.
---
## opencode quick setup
Project-level `opencode.json`:
### 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
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"hermes": {
"type": "remote",
"mcpServers": {
"squaremcp": {
"type": "http",
"url": "https://hermes.squaremcp.com/mcp",
"headers": {
"x-api-key": "YOUR_MCP_API_KEY"
}
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}
```
Full instructions: [OPENCODE.md](./OPENCODE.md)
### 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)
---
@@ -110,34 +132,24 @@ Full instructions: [OPENCODE.md](./OPENCODE.md)
```bash
npm install
cp .env.example .env
cp .env.example .env # fill in credentials
npm run dev
curl http://localhost:3456/health
```
The local server runs on port `3456` by default.
Server runs on port `3456` by default.
---
## Deployment
Production deployment notes are in:
See [DEPLOY.md](./DEPLOY.md) for the full deployment runbook.
1. [DEPLOY.md](./DEPLOY.md)
2. `hermes-k8s.yaml`
SquareMCP product-site docs live under:
1. [`product/site`](./product/site)
2. [`product/README.md`](./product/README.md)
3. [`videos/remotion-demo`](./videos/remotion-demo/README.md) for SquareMCP video production assets and render workflows
---
## Notes
The historical docs in this repo started from an email-only Claude-focused setup. Current deployment and setup guidance should follow:
1. the `hermes.squaremcp.com` domain
2. Streamable HTTP `/mcp` as the default transport
3. the dedicated client setup docs linked above
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
```