# MCP tools

> Every tool on the public and admin MCP servers, with arguments and examples.

## Servers

| Server | URL | Auth |
| --- | --- | --- |
| Public | `https://jenksguo.xyz/mcp` | none |
| Admin | `https://jenksguo.xyz/mcp/admin` | `Authorization: Bearer <admin token>` |
| Local (stdio) | `jenks mcp` / `jenks mcp --admin` | env `JENKSGUO_ADMIN_TOKEN` for admin |

Transport: Streamable HTTP, stateless, JSON-RPC 2.0 over POST (protocol `2025-06-18`). `GET` on either URL returns a discovery document. Server name `jenksguo`, version 1.1.0.

```bash
curl -s https://jenksguo.xyz/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_brief","arguments":{}}}'
```

# Public tools

## `get_brief` — Get Jenks's brief

A one-page Markdown brief about Jenks Guo: positioning, current role, career arc, strengths, languages, contact, and how to explore further. Start here.

- **MCP:** `get_brief` on `https://jenksguo.xyz/mcp`
- **REST:** `GET /api/v1/brief`
- **CLI:** `jenks brief`

_No arguments._

```bash
curl -s "https://jenksguo.xyz/api/v1/brief"
```

## `list_experience` — List experience

List Jenks's experiences, projects, community roles and education (newest first), optionally filtered by industry tag, role lens or kind. Returns short forms: title, organisation, period, summary, key result, page URL.

- **MCP:** `list_experience` on `https://jenksguo.xyz/mcp`
- **REST:** `GET /api/v1/entries?tag=&lens=&kind=&locale=`
- **CLI:** `jenks list [--tag it] [--lens solution-architect] [--kind project]`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `tag` | `it` · `engineering` · `ai` · `devrel` · `web3` · `business` · `marketing` · `consulting` · `hospitality` · `community` · `creative` | no |  |
| `lens` | `head-of-ai` · `ai-transformation-consultant` · `engineering-manager` · `solution-architect` · `system-integrator` · `support-engineer` · `ict-specialist` · `developer-advocate` · `developer-evangelist` · `digital-marketer` · `hospitality` | no |  |
| `kind` | `experience` · `education` · `community` · `project` | no |  |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.xyz/api/v1/entries"
```

## `get_entry` — Get one entry

Full long-form write-up of one experience, project, community role or education entry by slug: overview, what Jenks did, achievements, why it matters to employers, key results, skills, proof links.

- **MCP:** `get_entry` on `https://jenksguo.xyz/mcp`
- **REST:** `GET /api/v1/entries/{slug}?locale=`
- **CLI:** `jenks get <slug>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `slug` | string | yes | Entry slug, e.g. xero-developer-evangelist |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.xyz/api/v1/entries/xero-developer-evangelist"
```

## `list_lenses` — List role lenses

The role lenses employers can view Jenks through (Head of AI, solution architect, developer advocate, digital marketer, hospitality…) with a pitch, honest gaps and evidence counts.

- **MCP:** `list_lenses` on `https://jenksguo.xyz/mcp`
- **REST:** `GET /api/v1/lenses?locale=`
- **CLI:** `jenks lenses`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.xyz/api/v1/lenses"
```

## `search_jenks` — Search the corpus

Keyword search across every entry and document. Returns the best-matching passages with their slugs.

- **MCP:** `search_jenks` on `https://jenksguo.xyz/mcp`
- **REST:** `GET /api/v1/search?q=`
- **CLI:** `jenks search "<query>"`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `query` | string | yes |  |

```bash
curl -s "https://jenksguo.xyz/api/v1/search"
```

## `get_document` — Get a document

One of Jenks's reference documents: profile (core profile), credentials (education, certifications), capabilities (capability → evidence map), talks (talks, podcasts, writing), thinking (worldview).

- **MCP:** `get_document` on `https://jenksguo.xyz/mcp`
- **REST:** `GET /api/v1/documents/{name}?locale=`
- **CLI:** `jenks doc <name>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | `profile` · `credentials` · `capabilities` · `talks` · `thinking` | yes |  |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |

```bash
curl -s "https://jenksguo.xyz/api/v1/documents/credentials"
```

## `ask_jenks` — Ask Jenks's assistant

Ask the Ask Jenks assistant a natural-language question (role fit, consulting scoping, AI transformation advice, STAR stories, governance…). It runs its own tools over the corpus and answers in the requested language. Rate-limited.

- **MCP:** `ask_jenks` on `https://jenksguo.xyz/mcp`
- **REST:** `POST /api/v1/ask`
- **CLI:** `jenks ask "<question>"`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `question` | string | yes |  |
| `locale` | `en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo` | no | Language for translated fields (default en). |
| `history` | array | no | Optional earlier turns. |

```bash
curl -s -X POST https://jenksguo.xyz/api/v1/ask \
  -H 'content-type: application/json' \
  -d '{"question":"Is Jenks a fit for a Head of AI role?"}'
```

# Admin tools

## `admin_schema` — Content schema

The content model: entry fields and rules, tags, lenses, kinds, writable paths, documents, and editing conventions. Read this before writing.

- **MCP:** `admin_schema` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `GET /api/admin/schema` (admin token)
- **CLI:** `jenks admin schema`

_No arguments._

```bash
curl -s "https://jenksguo.xyz/api/admin/schema" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"
```

## `admin_list_files` — List content files

List editable content files on a branch (path, size, sha), optionally inside one folder such as content/corpus/experiences.

- **MCP:** `admin_list_files` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `GET /api/admin/files?dir=&branch=` (admin token)
- **CLI:** `jenks admin ls [dir]`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `dir` | string | no | e.g. content/corpus/projects (default: all content) |
| `branch` | `main` · `dev` | no | main publishes to jenksguo.xyz; dev previews on dev.jenksguo.xyz (default main). |

```bash
curl -s "https://jenksguo.xyz/api/admin/files" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"
```

## `admin_read_file` — Read a content file

Read the raw Markdown/JSON source of a content file (with its sha). Pass `path`, or `slug` for an entry, lens or skill.

- **MCP:** `admin_read_file` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `GET /api/admin/file?path=&slug=&branch=` (admin token)
- **CLI:** `jenks admin get <slug|path>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | no |  |
| `slug` | string | no |  |
| `branch` | `main` · `dev` | no | main publishes to jenksguo.xyz; dev previews on dev.jenksguo.xyz (default main). |

```bash
curl -s "https://jenksguo.xyz/api/admin/file" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"
```

## `admin_validate` — Validate a change

Validate file content against the content schema without committing. Returns a list of problems (empty = valid).

- **MCP:** `admin_validate` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `POST /api/admin/validate` (admin token)
- **CLI:** `jenks admin validate <path> <file>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | yes |  |
| `content` | string | yes |  |

```bash
curl -s -X POST https://jenksguo.xyz/api/admin/validate \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","content":"<content>"}'
```

## `admin_write_file` — Create or update a content file

Validate and commit one content file (create or replace). Publishing is automatic: CI re-translates changed entries into all languages, rebuilds and deploys (main → jenksguo.xyz, dev → dev.jenksguo.xyz) in a few minutes.

- **MCP:** `admin_write_file` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `PUT /api/admin/file` (admin token)
- **CLI:** `jenks admin put <path> <file> -m <message>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | yes |  |
| `content` | string | yes |  |
| `message` | string | yes | Commit message |
| `branch` | `main` · `dev` | no | main publishes to jenksguo.xyz; dev previews on dev.jenksguo.xyz (default main). |

```bash
curl -s -X PUT https://jenksguo.xyz/api/admin/file \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","content":"<content>","message":"<message>"}'
```

## `admin_delete_file` — Delete a content file

Delete one content file (e.g. remove an entry) with a commit message. Git history keeps it recoverable.

- **MCP:** `admin_delete_file` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `DELETE /api/admin/file?path=&message=&branch=` (admin token)
- **CLI:** `jenks admin rm <path> -m <message>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | yes |  |
| `message` | string | yes |  |
| `branch` | `main` · `dev` | no | main publishes to jenksguo.xyz; dev previews on dev.jenksguo.xyz (default main). |

```bash
curl -s -X DELETE https://jenksguo.xyz/api/admin/file \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","message":"<message>"}'
```

## `admin_commit_changes` — Commit several files at once

Validate and commit several file changes as ONE commit. Each change is {path, content} or {path, delete: true}.

- **MCP:** `admin_commit_changes` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `POST /api/admin/changes` (admin token)
- **CLI:** `jenks admin commit <changes.json> -m <message>`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `changes` | array | yes |  |
| `message` | string | yes |  |
| `branch` | `main` · `dev` | no | main publishes to jenksguo.xyz; dev previews on dev.jenksguo.xyz (default main). |

```bash
curl -s -X POST https://jenksguo.xyz/api/admin/changes \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"changes":"<changes>","message":"<message>"}'
```

## `admin_ai_edit` — Draft an edit with AI

Ask the site's model to rewrite one content file from a plain-English instruction. Returns the proposed content, a diff and validation problems. Does NOT commit — review, then call admin_write_file.

- **MCP:** `admin_ai_edit` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `POST /api/admin/ai-edit` (admin token)
- **CLI:** `jenks admin ai-edit <slug|path> "<instruction>" [--apply]`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | no |  |
| `slug` | string | no |  |
| `instruction` | string | yes |  |
| `branch` | `main` · `dev` | no | main publishes to jenksguo.xyz; dev previews on dev.jenksguo.xyz (default main). |
| `content` | string | no | Optional unsaved file text to draft from (default: the saved file). |

```bash
curl -s -X POST https://jenksguo.xyz/api/admin/ai-edit \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"instruction":"<instruction>"}'
```

## `admin_deploy_status` — Deploy status

Recent CI runs (translate → build → deploy) with status, branch, commit and links.

- **MCP:** `admin_deploy_status` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `GET /api/admin/deploys?branch=` (admin token)
- **CLI:** `jenks admin deploys`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `branch` | `main` · `dev` | no | main publishes to jenksguo.xyz; dev previews on dev.jenksguo.xyz (default main). |

```bash
curl -s "https://jenksguo.xyz/api/admin/deploys" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"
```

## `admin_promote` — Promote dev to production

Merge the dev branch into main, publishing everything previewed on dev.jenksguo.xyz to jenksguo.xyz.

- **MCP:** `admin_promote` on `https://jenksguo.xyz/mcp/admin`
- **REST:** `POST /api/admin/promote` (admin token)
- **CLI:** `jenks admin promote`

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `message` | string | no |  |

```bash
curl -s -X POST https://jenksguo.xyz/api/admin/promote \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{}'
```