# herrington.ai Programmatic Interfaces & API Reference

Public machine-callable interfaces, Model Context Protocol (MCP) server endpoints, and knowledge corpora for external AI agents (e.g., Muse, Instinct, Claude Code, Cursor, and automated agents).

---

## 1. Conversational Chat API (`POST /api/chat`)

The conversational chat API provides direct programmatic access to the simulated **dh.sh** developer terminal agent powering [herrington.ai](https://herrington.ai). It is backed by Google Gemini with deep grounding on Daniel Herrington's systems engineering research, machine learning infrastructure papers, and enterprise AI leadership.

### Endpoint Details
- **URL**: `https://herrington.ai/api/chat`
- **Method**: `POST`
- **Authentication**: None (Public)
- **CORS**: Enabled (`Access-Control-Allow-Origin: *`)
- **Rate Limits**:
  - `10 requests / minute` per IP
  - `60 requests / hour` per IP

### Request Headers
| Header | Value | Description |
|---|---|---|
| `Content-Type` | `application/json` | Required |
| `Accept` | `application/json` | Recommended |

### Request Body Schema
```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "User question or prompt for dh.sh",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": ["query"]
}
```

#### Example Request
```bash
curl -X POST https://herrington.ai/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did Daniel do at Google and what is ML Goodput?"
  }'
```

### Response Schema

#### Success Response (`200 OK`)
```json
{
  "response": "At Google, I led product efforts for the CoreML frameworks team and critical serving infrastructure for Gemini models. In collaboration with DeepMind and Google Research, I co-authored the research paper 'ML Productivity Goodput in LLM Training' (arXiv:2502.06982) and open-sourced the measurement library in AI-Hypercomputer/ml-goodput-measurement to quantify non-overlapped compute in distributed TPU/GPU training clusters.",
  "model": "gemini-3.6-flash"
}
```

#### Error Responses
- **`400 Bad Request`**: Missing query parameter, empty string, or query exceeding 500 characters.
  ```json
  { "error": "Query exceeds maximum allowed length (500 characters)." }
  ```
- **`429 Too Many Requests`**: Rate limit exceeded for the caller's IP address.
  ```json
  {
    "error": "Rate limit exceeded. Please slow down your requests.",
    "retryAfterSec": 15
  }
  ```
- **`502 Bad Gateway` / `503 Service Unavailable`**: Upstream LLM gateway failure or unconfigured API key.

---

## 2. Remote Model Context Protocol (MCP) Server (`/mcp`)

The site exposes a public, read-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server conforming to the **Streamable HTTP transport specification** (MCP `2024-11-05`). External agents can discover and invoke tools to query research, retrieve raw essay markdown, inspect software projects, and ask questions.

### Endpoint Details
- **Streamable HTTP Endpoint**: `https://herrington.ai/mcp`
- **Legacy SSE Endpoint**: `https://herrington.ai/sse` (POST responses to `/message?sessionId=...`)
- **Authentication**: None for read-only tools (Public)
- **CORS**: Enabled (`Access-Control-Allow-Origin: *`, `GET, POST, OPTIONS, DELETE`)

### Supported Transports
1. **Streamable HTTP Transport (MCP 2024-11-05)**: Handled directly at `POST https://herrington.ai/mcp` with `Accept: application/json, text/event-stream`.
2. **Direct JSON-RPC 2.0 over HTTP POST**: Standard single-roundtrip JSON-RPC 2.0 requests with `Accept: application/json`.
3. **Server-Sent Events (SSE)**: `GET /mcp` (or `GET /sse`).

---

### Available Tools

Every tool provides a clear JSON input schema discoverable via the standard `tools/list` handshake.

#### 1. `search_essays`
Semantic TF-IDF search and ranking across Daniel Herrington's technical essays, systems papers, and case studies.
- **Arguments**:
  - `query` (string, required): Search query or technical topic (e.g., `"goodput"`, `"vibe coding"`, `"agent guardrails"`).
  - `limit` (number, optional): Maximum results to return (default: `5`, max: `20`).
- **Returns**: Ranked array of `[{ slug, title, excerpt, url }]`.

#### 2. `get_essay`
Retrieves the full unedited markdown text of a specific technical essay or research paper.
- **Arguments**:
  - `slug` (string, required): The essay slug (e.g., `"end-of-vibe-coding"`, `"beyond-peak-tflops"`).
- **Returns**: Raw markdown text without HTML or JSON wrappers to minimize token overhead.

#### 3. `list_projects`
Lists all personal engineering projects, smart display hardware, open-source repositories, and AI agent architectures.
- **Arguments**: None.
- **Returns**: Array of `[{ id, title, summary, url }]`.

#### 4. `get_project`
Retrieves complete architecture, design documentation, and case study detail for a specific project.
- **Arguments**:
  - `id` (string, required): Project identifier (e.g., `"danboard"`, `"dojo-zen"`, `"izzyland"`, `"hispanic-heritage-poster"`, `"american-detail-cleaning"`, `"in-browser-rag-engine"`).
- **Returns**: Full project architecture and case study as raw markdown.

#### 5. `ask_dhsh`
Proxies a question to the autonomous `dh.sh` simulated developer agent (powered by Gemini).
- **Arguments**:
  - `question` (string, required): The question to ask.
- **Rate Limit**: Max `30 requests / hour` per IP address.
- **Returns**: Plain text answer from the agent.

#### 6. `get_career_timeline`
Returns Daniel Herrington's structured career history, executive roles, and educational background.
- **Arguments**: None.
- **Returns**: Structured JSON array of `[{ role, org, period, highlights }]`.

#### 7. `get_knowme_profile`
**KnowMe MCP ("LinkedIn for Agents")**: Returns Daniel Herrington's complete machine-readable human dossier—combining verified voice-interviewed personal facts, daily AI stack & harnesses, contrarian theses, hardware fleet, coverage radar, and recent Wispr Flow interview answers.
- **Arguments**: None.
- **Returns**: Structured KnowMe MCP JSON dossier (`knowme-mcp/1.0`).

#### 8. `request_human_answer`
**KnowMe MCP ("Agent Missed-Call Queue")**: Submits a question directly into Daniel Herrington's next AI Interview session when an external agent needs personal context, opinions, or collaboration details not yet covered in the verified corpus.
- **Arguments**:
  - `question` (string, required): The specific question you want the AI Interviewer to ask Daniel in his next interview session.
  - `agent_name` (string, optional): Identifier of the calling agent (e.g., `"claude-code"`, `"cursor-agent"`, `"muse"`).
  - `context` (string, optional): Brief context on why your agent is asking this question.
- **Returns**: Confirmation JSON with the queued question ID and status.

---

### MCP Handshake & Tool Invocation Examples

#### Step 1: Initialize Session
```bash
curl -X POST https://herrington.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "muse", "version": "1.0.0" }
    }
  }'
```

#### Step 2: List Tools (`tools/list`)
```bash
curl -X POST https://herrington.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
```

#### Step 3: Call Tool (`tools/call` on `search_essays`)
```bash
curl -X POST https://herrington.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_essays",
      "arguments": {
        "query": "goodput",
        "limit": 3
      }
    }
  }'
```

#### Step 4: Fetch Raw Essay Markdown (`tools/call` on `get_essay`)
```bash
curl -X POST https://herrington.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_essay",
      "arguments": {
        "slug": "beyond-peak-tflops"
      }
    }
  }'
```

---

## 3. Static AI Agent Manifests

For indexers and answer engines (Perplexity, SearchGPT, Claude, Gemini):

| Path | Purpose | Format |
|---|---|---|
| [`https://herrington.ai/llms.txt`](https://herrington.ai/llms.txt) | Curated index conforming to the [llmstxt.org](https://llmstxt.org) standard. | Markdown Index |
| [`https://herrington.ai/llms-full.txt`](https://herrington.ai/llms-full.txt) | Complete unedited markdown text of every essay and publication, delimited with title and canonical URL. | Full Text Markdown |
| [`https://herrington.ai/data/article_index.json`](https://herrington.ai/data/article_index.json) | Pre-computed inverted index and TF-IDF term weights for sub-10ms in-browser RAG. | JSON Search Index |
| [`https://herrington.ai/data/projects.json`](https://herrington.ai/data/projects.json) | Complete metadata for all active projects, tech stacks, and live deployments. | JSON |