AI个人上下文与能力层

Beacon 2.0

Beacon is a personal context and capability layer for AI and software — the infrastructure beneath Yaka and any other agent (Claude Code, Codex) that needs to understand or act on one person's digital world.

Beacon is no longer "an MCP server". It is a transport-free core with thin adapters: MCP (stdio), HTTP (always-on), and events (later). Single-user by design.

See ARCHITECTURE.md for the full design. This README is the operational quickstart.

Layout (npm workspaces)

packages/core     Beacon Core — domain, connectors, context, capabilities. Transport-free.
packages/client   @beacon/client — typed HTTP SDK (consumed by Yaka).
apps/mcp          stdio adapter over core (Claude Code, Codex — local).
apps/http         always-on HTTP adapter over core (serves Yaka).

Core concepts

• Context (read): deterministic, cacheable retrieval. Never mutates. mail.search, calendar.events, today.brief, ...
• Capability (write): explicit prepare → confirm → execute. A model that can prepare an action can not execute it — confirmation mints a separate single-use token over the trusted path. mail.send, ...
• Registry: the architectural centre. Transports project it; they add no integration logic.

Setup

npm install
cp .env.example .env   # fill in integration secrets + Beacon credentials
npm run build

Production action persistence requires DATABASE_URL. Normal reads and prepare use BEACON_SERVICE_TOKEN; the trusted confirmation path additionally requires a separate BEACON_CONFIRM_TOKEN. Both credentials stay server-side.

Restore Gmail + Calendar authorization

Beacon requests only these Google scopes:

• https://www.googleapis.com/auth/gmail.readonly
• https://www.googleapis.com/auth/gmail.send
• https://www.googleapis.com/auth/calendar.readonly

Add http://127.0.0.1:53682/oauth2/callback to the OAuth client's authorized redirect URIs, make sure GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET exist in the local .env, then run:

npm run google:oauth

The helper uses offline consent, PKCE, and state validation. It never prints the refresh token. On success it replaces the token in the gitignored local .env and sets the four Google variables on Beacon's linked Railway production service without echoing their values.

Run

# MCP (stdio) — for Claude Code / Codex, locally
npm run mcp

# HTTP (always-on) — for Yaka
npm run http:dev     # dev (watch)
npm run http         # built

HTTP endpoints: GET /health, GET /openapi.json, GET /registry, POST /context/:name, POST /capabilities/:id/{prepare,confirm,execute}. All except /health and /openapi.json require Authorization: Bearer <BEACON_SERVICE_TOKEN>. The confirm endpoint also requires X-Beacon-Confirmation-Token: <BEACON_CONFIRM_TOKEN>.

MCP client config (local)

{
  "mcpServers": {
    "beacon": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/beacon/apps/mcp/src/index.ts"]
    }
  }
}

Test

npm test

Deployment

• Beacon HTTP → Railway (always-on, holds integration secrets in encrypted env).
• Railway PostgreSQL persists prepared actions, single-use authorization hashes, and the audit trail in the beacon schema.
• Beacon MCP stays local over stdio.