# AIOS MCP

A remote MCP (Model Context Protocol) server that turns Hua's AIOS Kernel
conventions into callable tools instead of prompt-only rules. Deployed on
Vercel, separate from `mcp-drive-server`. Personal, single-user use only.

Hard-scoped to ONE canonical Google Doc — the PROJECT-MANAGEMENT portfolio
doc — configured via `AIOS_PORTFOLIO_DOC_ID`. Tools never accept an
arbitrary `file_id`, so a write from this server can never land on the
wrong document.

Tools exposed at `/api/mcp`:

- `aios_list_sections` — read-only, lists the doc's top-level section headings
- `aios_get_section` — read-only, returns one section's full text (Focus Now, Registry, Cross-AI Recovery Queue, Backlog, Archived, ...)
- `aios_find_and_replace` — guarded in-place find/replace (refuses on 0 or >1 matches unless explicitly allowed), for editing an existing Registry row/field
- `aios_append_to_section` — inserts new text at the end of a named section, for adding a new Registry row / Recovery Queue entry / Backlog item

## 0. Reuse existing Google credentials — no new Cloud Console setup

This server reuses the SAME Google OAuth Client ID / Secret / Refresh Token
that `mcp-drive-server` already has (see that project's `Google Cloud.txt`
in Drive folder "MCP Server for Claude"). That refresh token already
carries the `https://www.googleapis.com/auth/drive` scope, which covers the
Docs API `documents.get` / `documents.batchUpdate` calls used here — no new
scope, no new OAuth Client, no re-authorization needed.

## 1. Environment variables

See `.env.example`. You need:

- `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` / `GOOGLE_REFRESH_TOKEN` — copy from mcp-drive-server's Vercel project settings
- `AIOS_PORTFOLIO_DOC_ID` — the canonical PROJECT-MANAGEMENT Google Doc's file ID
- `MCP_AUTH_TOKEN` — generate a new one: `openssl rand -hex 32`. This is separate from mcp-drive-server's token — a leak of one doesn't expose the other.

## 2. Local setup and test

```bash
npm install
cp .env.example .env.local
# fill in .env.local with the values from step 1
npm run typecheck   # tsc --noEmit
npm run dev         # starts http://localhost:3000
```

Test with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector@latest http://localhost:3000/api/mcp
```

## 3. Deploy

Push to a new GitHub repo (`aios-mcp`), then import into a NEW Vercel
project (do not reuse the mcp-drive-server project) and set the environment
variables from step 1 in Vercel project settings before the first deploy.

Expected final MCP endpoint: `https://<your-project>.vercel.app/api/mcp`

## 4. Connecting to a client

v1 uses a plain static Bearer-token check (`lib/auth.ts`) — simpler than
mcp-drive-server's OAuth 2.1 compatibility layer. This works directly with
any client that lets you set a fixed `Authorization: Bearer <token>` header
(MCP Inspector, many custom-connector "Advanced settings" screens, ChatGPT
API-key auth).

If you need to connect this to a client that only offers OAuth Client
ID/Secret fields (no raw bearer field) — e.g. Claude's custom-connector UI —
copy `lib/oauth.ts` and the `/api/oauth/*` routes from the mcp-drive-server
repo. They are generic OAuth 2.1 PKCE helpers, not Drive-specific, and drop
in unchanged; ask for that as a fast-follow if/when it's needed.

## Human Approval Gate

Per AIOS Core §5.12, this repo/deployment is an architecture change and its
first real Production promotion (pointing it at the live canonical doc from
a real client) needs Hua's explicit approval before regular use, same as any
other AIOS production deployment.