@hormonaly/mcp-server 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,403 @@
+# Hormonaly MCP Server
+
+Model Context Protocol (MCP) server for the [Hormonaly](https://hormonaly.ai) evidence platform.
+Exposes the Helix AI engine, protocol library, compound database, and admin tools to Claude Desktop and any MCP-compatible AI agent.
+
+---
+
+## Installation
+
+### Option A — npx / local build (recommended)
+
+```bash
+# Clone the repo and build
+git clone https://github.com/hormonaly/hormonaly-platform
+cd hormonaly-platform/mcp/hormonaly-mcp-server
+npm install
+npm run build
+```
+
+### Option B — Run from the repo directly
+
+```bash
+node /path/to/hormonaly-platform/mcp/hormonaly-mcp-server/dist/index.js
+```
+
+---
+
+## Configuration for Claude Desktop
+
+Add the following to your `claude_desktop_config.json`
+(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "hormonaly": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/hormonaly-platform/mcp/hormonaly-mcp-server/dist/index.js"
+      ],
+      "env": {
+        "HORMONALY_API_URL": "https://hormonaly.ai",
+        "HORMONALY_API_KEY": "hk_live_YOUR_PARTNER_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+---
+
+## Authentication
+
+### Helix API key (required for `helix_*` tools)
+
+Get your API key from the [Hormonaly Partner Portal](https://hormonaly.ai/partner).
+Keys start with `hk_live_` and are 72 characters long.
+
+Set via environment variable:
+```bash
+export HORMONALY_API_KEY=hk_live_...
+```
+
+Or pass per-call using the `api_key` parameter on any `helix_*` tool.
+
+### Session token (required for `user_*` tools)
+
+Get your session cookie from your browser:
+1. Log into [hormonaly.ai](https://hormonaly.ai)
+2. Open DevTools → Application → Cookies
+3. Copy the value of `connect.sid`
+
+```bash
+export HORMONALY_SESSION_TOKEN=s%3A...
+```
+
+Or pass per-call using the `session_token` parameter.
+
+### Admin session token (required for `admin_*` tools)
+
+Same as session token but for an admin account:
+```bash
+export HORMONALY_ADMIN_SESSION_TOKEN=s%3A...
+```
+
+Or pass per-call using the `admin_session_token` parameter.
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HORMONALY_API_URL` | `https://hormonaly.ai` | Base URL of the platform |
+| `HORMONALY_API_KEY` | — | Helix B2B API key (`hk_live_...`) |
+| `HORMONALY_SESSION_TOKEN` | — | User session cookie value |
+| `HORMONALY_ADMIN_SESSION_TOKEN` | — | Admin session cookie value |
+| `HTTP_PORT` | — | Set to run HTTP/SSE transport instead of stdio |
+
+---
+
+## HTTP/SSE Transport (for remote agents)
+
+Start the server in HTTP mode:
+
+```bash
+HTTP_PORT=3100 node dist/index.js
+# or
+node dist/index.js --http
+```
+
+Endpoints:
+- `GET  http://localhost:3100/sse`          — SSE stream (connect first)
+- `POST http://localhost:3100/messages`     — Send tool calls
+- `GET  http://localhost:3100/health`       — Health check
+
+---
+
+## Available Tools
+
+### Helix Tools (require Helix API key)
+
+#### `helix_query`
+Send a clinical question to the Helix AI engine. Returns an evidence-based answer with citations, confidence score, and GRADE rating.
+
+```json
+{
+  "question": "What is the optimal BPC-157 dose for gut repair?",
+  "language": "en",
+  "detail_level": "clinical",
+  "include_citations": true,
+  "include_three_lens": false,
+  "api_key": "hk_live_..."
+}
+```
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `question` | string | ✅ | — | Clinical question (max 10,000 chars) |
+| `language` | `en` \| `ar` | — | `en` | Response language |
+| `detail_level` | `clinical` \| `summary` | — | `clinical` | Response depth |
+| `include_citations` | boolean | — | `true` | Include PubMed citations |
+| `include_three_lens` | boolean | — | `false` | Include longevity/health/performance scoring |
+| `api_key` | string | — | env var | Override `HORMONALY_API_KEY` |
+
+---
+
+#### `helix_compare`
+Compare 2–3 compounds head-to-head. Returns structured comparison with use-case recommendations. **Requires Professional or Enterprise tier.**
+
+```json
+{
+  "compounds": ["semaglutide", "tirzepatide"],
+  "indication": "weight loss in type 2 diabetes",
+  "language": "en"
+}
+```
+
+**Parameters:**
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `compounds` | string[] | ✅ | — | 2–3 compound names |
+| `indication` | string | — | `"General comparison"` | Clinical context |
+| `language` | `en` \| `ar` | — | `en` | Response language |
+| `api_key` | string | — | env var | Override `HORMONALY_API_KEY` |
+
+---
+
+#### `helix_protocol`
+Get all protocols for a compound from the Helix API.
+
+```json
+{
+  "compound": "BPC-157",
+  "language": "en"
+}
+```
+
+---
+
+#### `helix_dossier_start`
+Start an async dossier generation job for a compound. Returns `job_id`. **Requires Professional or Enterprise tier.**
+
+```json
+{
+  "compound": "semaglutide",
+  "language": "en"
+}
+```
+
+#### `helix_dossier_status`
+Poll a dossier generation job by `job_id`.
+
+```json
+{
+  "job_id": "dossier_abc123"
+}
+```
+
+---
+
+### Protocol Tools (no auth required)
+
+#### `protocol_search`
+Search the protocol library by compound, condition, or category.
+
+```json
+{
+  "query": "testosterone replacement",
+  "category": "hormones",
+  "limit": 10
+}
+```
+
+#### `protocol_get`
+Get the full details of a protocol by ID or slug.
+
+```json
+{
+  "id": "semaglutide-weight-loss"
+}
+```
+
+#### `protocol_list_categories`
+List all protocol categories with protocol counts.
+
+```json
+{}
+```
+
+#### `protocol_get_interactions`
+Check for known interactions between a set of compounds. Uses the public `/api/interactions/for/:slug` endpoint — no authentication required.
+
+```json
+{
+  "compounds": ["semaglutide", "metformin", "insulin"]
+}
+```
+
+---
+
+### Evidence Tools (no auth required)
+
+#### `evidence_search`
+Search PubMed for research on a compound or condition.
+
+```json
+{
+  "compound": "BPC-157",
+  "max_results": 15
+}
+```
+
+#### `evidence_get`
+Get full details for a specific evidence record by ID.
+
+```json
+{
+  "id": "ev_12345"
+}
+```
+
+---
+
+### Compound Tools (no auth required)
+
+#### `compound_search`
+Search the compound database by name or category.
+
+```json
+{
+  "query": "GLP-1",
+  "category": "peptides"
+}
+```
+
+#### `compound_get_interactions`
+Get all known interactions for a specific compound.
+
+```json
+{
+  "slug": "semaglutide"
+}
+```
+
+---
+
+### User Tools (require session token)
+
+#### `user_get_profile`
+Get the current user's profile.
+
+```json
+{
+  "session_token": "s%3A..."
+}
+```
+
+#### `user_get_usage`
+Get AI usage statistics for the current user.
+
+```json
+{}
+```
+
+#### `user_get_saved_protocols`
+Get the list of protocols saved by the current user.
+
+```json
+{}
+```
+
+---
+
+### Admin Tools (require admin session token)
+
+#### `admin_get_stats`
+Get platform-wide statistics (users, protocols, AI costs).
+
+```json
+{
+  "admin_session_token": "s%3A..."
+}
+```
+
+#### `admin_list_users`
+List platform users with optional search and pagination.
+
+```json
+{
+  "limit": 20,
+  "offset": 0,
+  "search": "john@example.com"
+}
+```
+
+#### `admin_get_ai_costs`
+Get AI cost breakdown by model and endpoint.
+
+```json
+{
+  "days": 30
+}
+```
+
+---
+
+## Example Queries
+
+### Ask Helix about a peptide protocol
+> "Use helix_query to ask: What is the evidence for BPC-157 in tendon healing? Include citations."
+
+### Compare GLP-1 agonists
+> "Use helix_compare to compare semaglutide vs tirzepatide for weight loss in T2D."
+
+### Search protocols
+> "Use protocol_search to find all protocols for testosterone replacement therapy."
+
+### Check compound interactions
+> "Use protocol_get_interactions to check interactions between semaglutide, metformin, and insulin."
+
+### Get admin stats
+> "Use admin_get_stats to show me the platform usage overview."
+
+---
+
+## Tier Requirements
+
+| Tool | Minimum Tier |
+|------|-------------|
+| `helix_query` | Starter |
+| `helix_protocol` | Starter |
+| `helix_compare` | Professional |
+| `helix_dossier_start` | Professional |
+| `helix_dossier_status` | Professional |
+| `helix_deep_analysis` | Professional |
+| `run_clinical_workflow` | Professional |
+| `monitor_protocol_updates` | Starter |
+| All protocol/compound/evidence tools | No auth needed |
+| `user_*` tools | Registered user |
+| `admin_*` tools | Admin user |
+
+---
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Clean build
+npm run clean && npm run build
+
+# Run in stdio mode (for local testing)
+HORMONALY_API_KEY=hk_live_... node dist/index.js
+
+# Run in HTTP mode
+HTTP_PORT=3100 HORMONALY_API_KEY=hk_live_... node dist/index.js
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hormonaly/mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MCP server for the Hormonaly evidence platform \u2014 exposes Helix AI, protocol library, compounds, and evidence to Claude and other AI agents",
   "main": "dist/index.js",
   "bin": {