Skip to content

Commit e1da0a7

Browse files
hTraphTrap
committed
feat: add glama.json for MCP server claiming
1 parent 9443db2 commit e1da0a7

File tree

5 files changed

+346
-0
lines changed

5 files changed

+346
-0
lines changed

‎.claude/skills/gitopia/SKILL.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
name: gitopia
3+
description: |
4+
Gitopia workflow assistant for decentralized git collaboration. Contribute to
5+
repos, review PRs, hunt bounties, and manage DAO governance using Gitopia MCP
6+
tools. Use when: "fix issue", "review PR", "find bounties", "create proposal",
7+
"vote on proposal", "contribute to", "clone from gitopia", "push to gitopia",
8+
or any Gitopia/decentralized git workflow. Also use when the user references
9+
gitopia:// URLs, DAO governance, on-chain bounties, or LORE tokens.
10+
---
11+
12+
# Gitopia Workflow Assistant
13+
14+
You have access to 57 Gitopia MCP tools (`mcp__gitopia__*`) for decentralized git
15+
with on-chain governance, bounties, and DAO management. This skill routes you
16+
through opinionated workflows using those tools.
17+
18+
For a full tool reference, read `references/tools.md` in this skill's directory.
19+
20+
## Step 1: Detect Intent
21+
22+
Classify the user's request into one of these modes:
23+
24+
| Mode | Trigger phrases | What happens |
25+
|------|----------------|--------------|
26+
| **contribute** | "fix issue", "send PR", "contribute to", "work on" | Clone, branch, fix, push, PR |
27+
| **review** | "review PR", "check PR", "code review", "look at PR" | Fetch diff, analyze, comment |
28+
| **bounty** | "find bounties", "hunt bounties", "earn rewards", "claim bounty" | Discover, evaluate, pick, fix |
29+
| **govern** | "create proposal", "vote", "DAO members", "governance", "execute proposal" | DAO operations |
30+
| **develop** | "update the skill", "tool changed", "add workflow" | Maintain skill + server code |
31+
32+
If the intent is ambiguous, ask: "Are you looking to contribute code, review a PR,
33+
hunt bounties, or manage DAO governance?"
34+
35+
## Step 2: Setup (all modes)
36+
37+
1. Call `get_user_context` to get identity, wallet address, and DAO memberships.
38+
2. If the user mentions a DAO or org, call `set_active_dao` with the DAO name.
39+
3. Confirm the target repository (owner/name) if not already clear from context.
40+
41+
## Contribute Workflow
42+
43+
Goal: Fix an issue or make a contribution, ending with a merged-ready PR.
44+
45+
### Steps
46+
47+
1. **Understand the problem.** Call `get_issue` with the owner, repo name, and issue IID.
48+
Read the issue description, labels, and comments to understand what needs fixing.
49+
50+
2. **Get the code.** Call `git_clone` with `repo_url="gitopia://owner/repo"` and
51+
`local_path="repo-name"`. If the user doesn't have write access, ask whether to
52+
fork first (`fork_repository`).
53+
54+
3. **Create a feature branch.** Use your built-in git tools to create and checkout a
55+
branch like `fix/issue-N` or `feat/description`.
56+
57+
4. **Investigate and fix.** Use your built-in file search, read, and edit tools.
58+
Write tests if the project has a test suite.
59+
60+
5. **Commit and push.** Stage and commit with a message referencing the issue
61+
(e.g. "fix: resolve issue #N"). Then call `git_push` to publish.
62+
63+
6. **Open a PR.** Call `create_pull_request` with:
64+
- `owner`, `name`, `title`, `description`
65+
- `head_branch` (your feature branch)
66+
- `base_branch` (repo's default branch)
67+
- `issue_iids` to link the issue
68+
69+
7. **Comment on the issue.** Call `comment_on_issue` to note the PR was submitted.
70+
71+
### Decision Points
72+
73+
At each decision point, use the default unless the user has stated a preference.
74+
After asking, offer: "Want me to use this as your default going forward?"
75+
76+
| Decision | Default | When to ask |
77+
|----------|---------|-------------|
78+
| Fork first or clone directly? | Clone directly | When user may not have write access |
79+
| Base branch? | Repo's default branch | When repo has multiple active branches |
80+
| Link issues to PR? | Yes, link the issue being fixed | Always use default |
81+
| Auto-push after commit? | Yes | Always use default |
82+
83+
## Review Workflow
84+
85+
Goal: Review code changes in a PR and leave actionable feedback.
86+
87+
### Steps
88+
89+
1. **Get PR metadata.** Call `get_pull_request` with owner, name, and pull_iid.
90+
Note the title, description, author, and linked issues.
91+
92+
2. **Get the diff.** Call `get_pull_request_diff` with the same params.
93+
This returns unified diffs with per-file addition/deletion stats.
94+
95+
3. **Analyze each file.** For each changed file in the diff:
96+
- Check for correctness, security issues, and edge cases
97+
- If you need more context, call `get_file_contents` for the full file
98+
- Note specific line-level feedback
99+
100+
4. **Post review comments.** Call `comment_on_pull_request` with:
101+
- General feedback in `body`
102+
- For inline comments: include `diff_hunk`, `path`, and `position`
103+
104+
5. **Summarize.** Post a final comment with overall assessment: approve or
105+
request changes, with a summary of findings.
106+
107+
### Decision Points
108+
109+
| Decision | Default | When to ask |
110+
|----------|---------|-------------|
111+
| Post comments on-chain? | Yes | When user might want local-only review |
112+
| Merge after approval? | No, just comment | When user explicitly asks to merge |
113+
114+
## Bounty Workflow
115+
116+
Goal: Find high-value bounties, evaluate them, and execute the fix.
117+
118+
### Steps
119+
120+
1. **Discover bounties.** Call `list_bounties`. Optionally filter by state.
121+
122+
2. **Evaluate top candidates.** For each promising bounty:
123+
- Call `get_bounty` for full details (amount, expiry, state)
124+
- Call `get_issue` for the linked issue (complexity, requirements)
125+
126+
3. **Present evaluation.** Show a table with:
127+
- Bounty ID, amount (in LORE), expiry date
128+
- Issue title, complexity estimate, skills needed
129+
- Recommendation: which bounty has the best reward-to-effort ratio
130+
131+
4. **Execute.** When the user picks a bounty, run the Contribute Workflow
132+
for the linked issue.
133+
134+
### Decision Points
135+
136+
| Decision | Default | When to ask |
137+
|----------|---------|-------------|
138+
| Minimum amount filter? | Show all | When there are many bounties |
139+
| Auto-start contribute after picking? | Yes | Always use default |
140+
141+
## Govern Workflow
142+
143+
Goal: Manage DAO governance — members, proposals, voting, execution.
144+
145+
Detect the sub-intent:
146+
147+
| Sub-intent | Action |
148+
|-----------|--------|
149+
| "list members" | `set_active_dao` then `dao_list_members` with `dao` param |
150+
| "create proposal" | `set_active_dao` then `dao_submit_proposal` with `dao` param, `title`, `summary` |
151+
| "list proposals" | `dao_list_proposals` with `dao` param |
152+
| "vote" | `dao_get_proposal` to show details, then `dao_vote` with `proposal_id` and `option` |
153+
| "execute" | `dao_exec` with `proposal_id` (must have passed) |
154+
| "add/remove member" | `dao_update_members` with `dao` param and `member_updates` |
155+
156+
The `dao` parameter accepts DAO names directly — no need to look up group_id or
157+
group_policy_address first. The server resolves internally.
158+
159+
## Develop Workflow
160+
161+
Goal: Maintain the gitopia-mcp-server and keep this skill in sync.
162+
163+
When working on the MCP server codebase:
164+
165+
### After adding or modifying tools
166+
1. Update `references/tools.md` with the new/changed tool
167+
2. Update `toolTrustRequirements` in `internal/handler/trust.go`
168+
3. Update trust tests in `internal/handler/trust_test.go`
169+
4. If tool belongs to a toolset, update `toolsetMembership` in `internal/handler/toolsets.go`
170+
5. Add unit tests in `internal/handler/*_test.go` (dry-run, validation, no-client)
171+
6. Add E2E test case in appropriate `test/e2e/tier*_test.go`
172+
173+
### After finding bugs during skill usage
174+
1. File issue on Gitopia: `create_issue` on `Gitopia/gitopia-mcp-server`
175+
2. Create fix branch: `htrap/fix/description`
176+
3. Fix, test, push to both remotes (origin + gitopia)
177+
4. Create PR: `create_pull_request` linking the issue
178+
179+
### Test commands
180+
- Unit tests: `go test -race ./...`
181+
- E2E tests: `go test -tags integration -v -timeout 10m ./test/e2e/...`
182+
- Rebuild binary: `go build -o server ./cmd/server`
183+
- Rebuild Docker: `docker build -t gitopia-mcp-server:dev .`
184+
185+
## Error Recovery
186+
187+
When a tool call fails, check for these common errors before retrying:
188+
189+
| Error message | Cause | Fix |
190+
|--------------|-------|-----|
191+
| "pending packfile" | Previous push still processing | Wait 15s, retry |
192+
| "account sequence mismatch" | Stale sequence number | Automatic retry (server handles up to 3x) |
193+
| "couldn't find remote ref" | Repository is empty | Use `bootstrap_repo` to create initial content |
194+
| "owner id must consist minimum 3 chars" | Using numeric DAO ID | Pass DAO name instead (fixed in v0.1.1) |
195+
| "invalid assignee" | Username instead of address | Server resolves automatically (v0.1.1+) |
196+
| "pullRequest already exists" | PR already open for this branch | Check existing PRs with `list_pull_requests` |
197+
| "rate limit exceeded" | Too many chain writes | Wait and retry, or use `batch_execute` |
198+
199+
## User Preferences
200+
201+
At each decision point, check if the user has previously stated a preference in
202+
this conversation. If not, ask with the default shown, then offer:
203+
204+
"Want me to use this as your default for the rest of this session?"
205+
206+
If yes, remember the preference and skip asking for that decision going forward.
207+
This lets power users set defaults once and flow through workflows without interruption.

‎.claude/skills/gitopia/references/tools.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Gitopia MCP Tools Reference (57 tools)
2+
3+
## Context Management (4)
4+
| Tool | Description |
5+
|------|-------------|
6+
| `get_user_context` | Get identity, wallet address, and DAO memberships |
7+
| `set_active_dao` | Switch operations to a DAO context |
8+
| `refresh_user_context` | Reload context after account changes |
9+
| `claim_fee_grant` | Claim fee grant from Gitopia faucet |
10+
11+
## User (1)
12+
| Tool | Description |
13+
|------|-------------|
14+
| `create_user` | Create on-chain Gitopia user for wallet |
15+
16+
## Repository Management (7)
17+
| Tool | Description |
18+
|------|-------------|
19+
| `list_repos` | List repositories for a user or DAO |
20+
| `create_repo` | Create remote repository on Gitopia |
21+
| `get_repo` | Get repository details (id, description, forks) |
22+
| `list_branches` | List branches with SHA |
23+
| `get_file_contents` | Read file from remote repo without cloning |
24+
| `fork_repository` | Fork a repository |
25+
| `toggle_repository_forking` | Enable/disable forking |
26+
27+
## Metadata (5)
28+
| Tool | Description |
29+
|------|-------------|
30+
| `list_tags` | List version tags |
31+
| `list_commits` | Browse commit history for a branch |
32+
| `list_releases` | List published releases |
33+
| `list_labels` | List repository labels |
34+
| `create_release` | Publish a release for a tagged version |
35+
36+
## Labels (2)
37+
| Tool | Description |
38+
|------|-------------|
39+
| `create_label` | Create label (on-chain) |
40+
| `delete_label` | Delete label (on-chain, irreversible) |
41+
42+
## Issue Management (5)
43+
| Tool | Description |
44+
|------|-------------|
45+
| `list_issues` | List issues for a repository |
46+
| `get_issue` | Get full issue details (labels, assignees, bounties) |
47+
| `create_issue` | Create issue (on-chain) |
48+
| `comment_on_issue` | Comment on issue (on-chain) |
49+
| `update_issue` | Update state, labels, assignees (atomic single tx) |
50+
51+
## Pull Request Management (6)
52+
| Tool | Description |
53+
|------|-------------|
54+
| `list_pull_requests` | List PRs for a repository |
55+
| `get_pull_request` | Get full PR details (head, base, reviewers) |
56+
| `get_pull_request_diff` | Get unified diff with per-file stats |
57+
| `create_pull_request` | Create PR (on-chain, supports issue linking) |
58+
| `comment_on_pull_request` | Comment on PR (general or inline) |
59+
| `merge_pull_request` | Merge PR (on-chain) |
60+
61+
## Git Operations (5)
62+
| Tool | Description |
63+
|------|-------------|
64+
| `git_clone` | Clone Gitopia repo to local workspace |
65+
| `git_push` | Push commits to remote |
66+
| `create_feature_branch` | Create and checkout new branch |
67+
| `sync_with_remote` | Fetch and merge/rebase from remote |
68+
| `commit_and_push_changes` | Stage + commit + push in one step |
69+
70+
## Workflow Orchestrators (3)
71+
| Tool | Description |
72+
|------|-------------|
73+
| `bootstrap_repo` | Create remote + init local + README + push |
74+
| `create_feature_branch_pr` | Branch + changes + commit + push + PR |
75+
| `update_feature_branch` | Add commits to existing branch/PR |
76+
77+
Note: These are in the `workflow` toolset (hidden when `TOOLSETS=core`).
78+
79+
## DAO (2)
80+
| Tool | Description |
81+
|------|-------------|
82+
| `get_dao` | Get DAO details (group_id, group_policy_address) |
83+
| `create_dao` | Create new DAO with members and voting |
84+
85+
## DAO Governance (7)
86+
| Tool | Description |
87+
|------|-------------|
88+
| `dao_list_members` | List members and voting weights (accepts `dao` name) |
89+
| `dao_list_proposals` | List proposals (accepts `dao` name) |
90+
| `dao_get_proposal` | Get proposal details with tally results |
91+
| `dao_update_members` | Add/remove members (accepts `dao` name) |
92+
| `dao_submit_proposal` | Create governance proposal (accepts `dao` name) |
93+
| `dao_vote` | Cast vote (yes/no/abstain/no_with_veto) |
94+
| `dao_exec` | Execute a passed proposal |
95+
96+
## Bounties (6)
97+
| Tool | Description |
98+
|------|-------------|
99+
| `list_bounties` | Discover available bounties |
100+
| `get_bounty` | Get bounty details (amount, expiry, state) |
101+
| `create_bounty` | Attach reward to an issue |
102+
| `update_bounty` | Extend bounty expiry |
103+
| `close_bounty` | Deactivate bounty |
104+
| `delete_bounty` | Permanently remove bounty |
105+
106+
## Batch & Approval (4)
107+
| Tool | Description |
108+
|------|-------------|
109+
| `batch_execute` | Execute up to 10 ops in single atomic tx |
110+
| `confirm_transaction` | Broadcast pending transaction (approval mode) |
111+
| `reject_transaction` | Cancel pending transaction |
112+
| `list_pending_transactions` | View pending transactions |

‎.github/workflows/release.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,11 @@ env:
1212
permissions:
1313
contents: write
1414
packages: write
15+
id-token: write
1516

1617
jobs:
1718
goreleaser:
19+
needs: [docker]
1820
runs-on: ubuntu-latest
1921
steps:
2022
- name: Checkout
@@ -61,6 +63,8 @@ jobs:
6163
type=semver,pattern={{version}}
6264
type=semver,pattern={{major}}.{{minor}}
6365
type=raw,value=latest
66+
labels: |
67+
io.modelcontextprotocol.server.name=io.github.gitopia/gitopia-mcp-server
6468
6569
- name: Set up QEMU
6670
uses: docker/setup-qemu-action@v3

‎.goreleaser.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,3 +50,20 @@ changelog:
5050
release:
5151
draft: false
5252
prerelease: auto
53+
54+
mcp:
55+
name: io.github.gitopia/gitopia-mcp-server
56+
title: "Gitopia MCP Server"
57+
description: "Decentralized Git with on-chain governance, bounties, and DAOs. Tools for repos, issues, PRs, labels, releases, bounties, and DAO proposals. Auto-wallet on first use, trust tiers, and approval mode for human-in-the-loop."
58+
homepage: "https://gitopia.com"
59+
auth:
60+
type: github-oidc
61+
repository:
62+
url: "https://github.com/gitopia/gitopia-mcp-server"
63+
source: github
64+
id: "1199353361"
65+
packages:
66+
- registry_type: oci
67+
identifier: "ghcr.io/gitopia/gitopia-mcp-server:{{ .Version }}"
68+
transport:
69+
type: stdio

‎glama.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"$schema": "https://glama.ai/mcp/schemas/server.json",
3+
"maintainers": [
4+
"hTrap"
5+
]
6+
}

0 commit comments

Comments
 (0)