giovannino/forgejo-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
forgejo-mcp/openspec/specs/org-teams/spec.md
Christoph Görn 7eb8a34234
 docs: 📝 archive 5 delivered openspec changes, track 2 unimplemented 
Sweep: assessed all 7 active openspec changes against the codebase.
Five had landed implementations (bounded-text, org-label, org-management,
code-review-skill, list-milestones-labels) — archived under
openspec/changes/archive/2026-05-12-* and their deltas folded into
openspec/specs/. Two remain unimplemented: add-releases-support
(operation/release/ missing despite proposal PR #129) and
forgejo-action-code-review (.forgejo/workflows/claude-code-review.yml
missing despite spec deltas).

Beads: reopened forgejo-mcp-0ep (releases impl) with notes on actual
status; created forgejo-mcp-673 for the action workflow impl.
2026-05-12 15:38:15 +02:00

4.8 KiB
Raw Permalink Blame History

org-teams Specification

Purpose

TBD - created by archiving change add-org-management. Update Purpose after archive.

Requirements

Requirement: List organization teams

The system SHALL provide a list_org_teams MCP tool that lists teams in an organization. The tool SHALL accept:

  • org (required): organization name
  • page (required, default 1): page number
  • limit (required, default 100): page size

The tool SHALL return a list of team objects including id, name, description, and permission level.

Scenario: List teams in an organization

  • WHEN user calls list_org_teams with org set to an existing organization
  • THEN the system returns a list of team objects for that organization

Scenario: List teams with pagination

  • WHEN user calls list_org_teams with org, page set to 1, limit set to 10
  • THEN the system returns at most 10 teams from the first page

Requirement: Create organization team

The system SHALL provide a create_org_team MCP tool that creates a team within an organization. The tool SHALL accept:

  • org (required): organization name
  • name (required): team name
  • description (optional): team description
  • permission (optional): access level — one of read, write, admin (default: read)
  • can_create_org_repo (optional, default false): whether team members can create repos in the org
  • includes_all_repositories (optional, default false): whether the team has access to all org repos

The tool SHALL return the created team object including its id.

Scenario: Create a team with defaults

  • WHEN user calls create_org_team with org set to an existing organization and name set to "developers"
  • THEN the system creates a team with read permission and returns the team object with its assigned id

Scenario: Create a team with custom permissions

  • WHEN user calls create_org_team with org, name, permission set to "write", and includes_all_repositories set to true
  • THEN the system creates a team with write access to all repositories and returns the team object

Scenario: Create team in non-existent organization

  • WHEN user calls create_org_team with org set to a name that does not exist
  • THEN the system returns an error indicating the organization was not found

Requirement: Add team member

The system SHALL provide an add_team_member MCP tool that adds a user to a team. The tool SHALL accept:

  • team_id (required): numeric team ID
  • user (required): username to add

The tool SHALL return a success confirmation.

Scenario: Add user to team

  • WHEN user calls add_team_member with a valid team_id and user
  • THEN the system adds the user to the team and returns a success message

Scenario: Add user to non-existent team

  • WHEN user calls add_team_member with a team_id that does not exist
  • THEN the system returns an error indicating the team was not found

Requirement: Remove team member

The system SHALL provide a remove_team_member MCP tool that removes a user from a team. The tool SHALL accept:

  • team_id (required): numeric team ID
  • user (required): username to remove

The tool SHALL return a success confirmation.

Scenario: Remove user from team

  • WHEN user calls remove_team_member with a valid team_id and user who is a current member
  • THEN the system removes the user from the team and returns a success message

Requirement: Add repository to team

The system SHALL provide an add_team_repo MCP tool that grants a team access to a repository. The tool SHALL accept:

  • team_id (required): numeric team ID
  • org (required): organization name (owner of the repo)
  • repo (required): repository name

The tool SHALL return a success confirmation.

Scenario: Add repo to team

  • WHEN user calls add_team_repo with a valid team_id, org, and repo
  • THEN the system adds the repository to the team's access list and returns a success message

Scenario: Add non-existent repo to team

  • WHEN user calls add_team_repo with a valid team_id but a repo that does not exist
  • THEN the system returns an error indicating the repository was not found

Requirement: Remove repository from team

The system SHALL provide a remove_team_repo MCP tool that revokes a team's access to a repository. The tool SHALL accept:

  • team_id (required): numeric team ID
  • org (required): organization name (owner of the repo)
  • repo (required): repository name

The tool SHALL return a success confirmation.

Scenario: Remove repo from team

  • WHEN user calls remove_team_repo with a valid team_id, org, and repo that the team currently has access to
  • THEN the system removes the repository from the team's access list and returns a success message