# Vibe Blog — machine-readable notes for LLMs and agents

## What this site is
A small blog about **AI** and **vibe coding**: short essays in Markdown with YAML frontmatter (`title`, `slug`, `date`, `tags`, `summary`, `draft`).

## Canonical URLs (resolved from NEXT_PUBLIC_SITE_URL)
Public site origin: `https://blog.vibegarage.ai`

- Home: https://blog.vibegarage.ai/
- Post: https://blog.vibegarage.ai/posts/<slug>
- Tag index: https://blog.vibegarage.ai/tags/<tag>
- Search UI: https://blog.vibegarage.ai/search?q=<query>&mode=keyword|semantic|hybrid
- This document: https://blog.vibegarage.ai/llms.txt

## MCP (Streamable HTTP)
Configure Cursor (or other MCP clients) using your **public blog origin** — not a placeholder host.

### Recommended MCP URL (via this Next.js app)
**Endpoint:** `https://blog.vibegarage.ai/mcp`

Same host as the blog. The Next.js service proxies to your Hono API; set **API_URL** (or **NEXT_PUBLIC_API_URL**) on the **web** service to your API base URL (e.g. internal Railway URL or `http://localhost:3001` in dev).


### Authentication
- The MCP `initialize` result includes **server `instructions`** describing Bearer auth; authoring tools also declare `_meta["vibe-blog/authentication"]` (HTTP Bearer, value = API `MCP_AUTH_TOKEN`).
- In Cursor, set an MCP **header** `Authorization: Bearer <your token>` (same string as `MCP_AUTH_TOKEN` on the API). The model does not "type" the key for you—configure it in MCP server settings.
- **Read tools** (`list_posts`, `get_post`, `search_posts`): no `Authorization` header **unless** the API sets `MCP_REQUIRE_AUTH=true` (then every request must include a valid Bearer).
- **Authoring tools**: always need `Authorization: Bearer` matching `MCP_AUTH_TOKEN` (when that env var is set; if unset, authoring is disabled).

### Read tools
- `list_posts` — published posts metadata. Optional: `tag`, `limit`, `offset`.
- `get_post` — full post (`frontmatter` + markdown `body`) for a `slug`. Drafts only with a valid authoring token.
- `search_posts` — `query` and optional `mode`: `keyword` | `semantic` | `hybrid`

### Authoring tools (Bearer required)
`create_post`, `update_post`, `delete_post`, `publish_post`, `unpublish_post`, `list_drafts`

### REST (optional)
The API exposes REST at its own base URL (same as API_URL): `/posts`, `/posts/:slug`, `/search`, etc.

## Operational notes
- Keyword search: SQLite FTS5 on the API.
- Semantic/hybrid: OpenAI embeddings + sqlite-vec on the API when configured.
- After writes, optional `POST /api/revalidate` on this site when `WEB_REVALIDATE_URL` and `REVALIDATE_SECRET` are set on the API.

---
Resolved at request: site from NEXT_PUBLIC_SITE_URL.