forked from farhoodlabs/skills
184 lines
6.1 KiB
Markdown
184 lines
6.1 KiB
Markdown
---
|
|
name: gitea-wiki
|
|
description: Manage Gitea wiki pages. Use when user asks about wiki pages, or when agent reaches for GitHub wiki, github wiki API, or any wiki operation on a Gitea-hosted repo. (Child skill of `gitea` parent skill.)
|
|
version: 1.1.0
|
|
---
|
|
|
|
# Gitea Wiki Management
|
|
|
|
## Overview
|
|
|
|
Gitea wikis are git-backed Markdown pages attached to a repository. The MCP server exposes them through two consolidated tools (`wiki_read`, `wiki_write`); the REST API at `/api/v1/repos/{owner}/{repo}/wiki/...` is the fallback. `tea` has no wiki subcommands.
|
|
|
|
## Interaction Methods
|
|
|
|
| Priority | Method | Notes |
|
|
|----------|--------|-------|
|
|
| **Primary** | MCP `mcp__gitea__wiki_read` / `mcp__gitea__wiki_write` | Configured in repo `.mcp.json`; auth via `GITEA_TOKEN` |
|
|
| Fallback | REST API via `curl` | For automation outside an MCP-aware client |
|
|
| — | `tea` CLI | Not supported — `tea` has no wiki commands |
|
|
|
|
## MCP tools
|
|
|
|
Both tools take `owner`, `repo`, and a `method` discriminator.
|
|
|
|
### `wiki_read` — methods
|
|
|
|
| `method` | Other args | Returns |
|
|
|----------|-----------|---------|
|
|
| `list` | — | All page titles + slugs + content URLs |
|
|
| `get` | `pageName` | Page metadata + raw markdown |
|
|
| `get_revisions` | `pageName` | Commit history for that page |
|
|
|
|
### `wiki_write` — methods
|
|
|
|
| `method` | Required args | Notes |
|
|
|----------|--------------|-------|
|
|
| `create` | `title`, `content` | Title becomes the slug (spaces → dashes). Optional `message` for commit msg. |
|
|
| `update` | `pageName`, `content` | `pageName` is the slug. `title` and `message` are optional. |
|
|
| `delete` | `pageName` | Requires write access to the wiki. |
|
|
|
|
### Examples
|
|
|
|
List pages in `farh/example`:
|
|
```
|
|
mcp__gitea__wiki_read(method="list", owner="farh", repo="example")
|
|
```
|
|
|
|
Read the `Home` page:
|
|
```
|
|
mcp__gitea__wiki_read(method="get", owner="farh", repo="example", pageName="Home")
|
|
```
|
|
|
|
Create `Installation-Guide`:
|
|
```
|
|
mcp__gitea__wiki_write(
|
|
method="create",
|
|
owner="farh", repo="example",
|
|
title="Installation Guide",
|
|
content="# Installation\n\nStep 1...",
|
|
message="docs(wiki): add installation guide"
|
|
)
|
|
```
|
|
|
|
Update existing page:
|
|
```
|
|
mcp__gitea__wiki_write(
|
|
method="update",
|
|
owner="farh", repo="example",
|
|
pageName="Installation-Guide",
|
|
content="# Installation\n\nUpdated...",
|
|
message="docs(wiki): update installation"
|
|
)
|
|
```
|
|
|
|
Delete page:
|
|
```
|
|
mcp__gitea__wiki_write(method="delete", owner="farh", repo="example", pageName="Old-Page")
|
|
```
|
|
|
|
## REST API fallback
|
|
|
|
The MCP server wraps these endpoints. Use `curl` directly only when MCP isn't reachable.
|
|
|
|
| Endpoint | Method | Purpose |
|
|
|----------|--------|---------|
|
|
| `/repos/{owner}/{repo}/wiki/pages` | GET | List all pages |
|
|
| `/repos/{owner}/{repo}/wiki/page/{slug}` | GET | Get a page (raw markdown by default; add `?format=html` for rendered HTML) |
|
|
| `/repos/{owner}/{repo}/wiki/revisions/{slug}` | GET | Page commit history |
|
|
| `/repos/{owner}/{repo}/wiki/new` | POST | Create a page |
|
|
| `/repos/{owner}/{repo}/wiki/page/{slug}` | PATCH | Update a page |
|
|
| `/repos/{owner}/{repo}/wiki/page/{slug}` | DELETE | Delete a page |
|
|
|
|
> Slug rules: take the title, replace spaces with `-`, drop characters that aren't `[A-Za-z0-9_./-]`. Gitea returns the canonical slug as `sub_url` in the page metadata — when in doubt, list first and read the slug back.
|
|
|
|
### Auth
|
|
|
|
```bash
|
|
export GITEA_TOKEN=<your-token>
|
|
# Repo MCP config uses: Authorization: Bearer ${GITEA_TOKEN}
|
|
```
|
|
|
|
### Listing pages
|
|
|
|
```bash
|
|
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/pages" \
|
|
-H "Authorization: Bearer $GITEA_TOKEN" \
|
|
| jq -r '.[] | "\(.title)\t\(.sub_url)"'
|
|
```
|
|
|
|
### Creating a page
|
|
|
|
```bash
|
|
curl -s -X POST "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/new" \
|
|
-H "Authorization: Bearer $GITEA_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"title":"Installation Guide","content":"# Installation\n\nStep 1..."}'
|
|
```
|
|
|
|
`content_base64` is also accepted in place of `content` for binary-safe payloads.
|
|
|
|
### Updating a page
|
|
|
|
```bash
|
|
curl -s -X PATCH "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/Installation-Guide" \
|
|
-H "Authorization: Bearer $GITEA_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"content":"# Installation\n\nUpdated..."}'
|
|
```
|
|
|
|
### Deleting a page
|
|
|
|
```bash
|
|
curl -s -X DELETE "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/Installation-Guide" \
|
|
-H "Authorization: Bearer $GITEA_TOKEN"
|
|
```
|
|
|
|
### Rendered HTML
|
|
|
|
```bash
|
|
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/Home?format=html" \
|
|
-H "Authorization: Bearer $GITEA_TOKEN"
|
|
```
|
|
|
|
### Upsert pattern (no dedicated endpoint)
|
|
|
|
```bash
|
|
status=$(curl -s -o /dev/null -w "%{http_code}" \
|
|
"$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/$SLUG" \
|
|
-H "Authorization: Bearer $GITEA_TOKEN")
|
|
|
|
if [ "$status" = "200" ]; then
|
|
curl -s -X PATCH "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/$SLUG" \
|
|
-H "Authorization: Bearer $GITEA_TOKEN" -H "Content-Type: application/json" \
|
|
-d "{\"content\":$(jq -Rs . <body.md)}"
|
|
else
|
|
curl -s -X POST "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/new" \
|
|
-H "Authorization: Bearer $GITEA_TOKEN" -H "Content-Type: application/json" \
|
|
-d "{\"title\":\"$TITLE\",\"content\":$(jq -Rs . <body.md)}"
|
|
fi
|
|
```
|
|
|
|
## Wiki structure notes
|
|
|
|
- Pages are Markdown files in a dedicated `.wiki` git branch.
|
|
- Slug = sanitized title; revision history is per page.
|
|
- The whole wiki can be cloned: `git clone $GITEA_SERVER_URL/$OWNER/$REPO.wiki.git`.
|
|
|
|
## Guidelines
|
|
|
|
### Do
|
|
- Prefer `wiki_read` / `wiki_write` MCP calls — they hide the slug/encoding rules.
|
|
- When unsure of a slug, `wiki_read` with `method="list"` and pick the canonical slug from the response.
|
|
- Add a `message` on writes — wiki commits are visible in the page revision log.
|
|
|
|
### Don't
|
|
- Assume the slug equals the title. Spaces become `-`; punctuation gets stripped.
|
|
- Use the REST API when MCP is available — MCP handles auth and slug encoding.
|
|
- Apply GitHub Wiki API conventions; Gitea's endpoints differ in path shape (`wiki/page/{slug}`, `wiki/new`).
|
|
|
|
## References
|
|
|
|
- [Gitea MCP server](https://gitea.com/gitea/gitea-mcp)
|
|
- [Gitea Wiki API](https://docs.gitea.com/api/next/#tag/repository/operation/repoGetWikiPages)
|