Forgejo Projects MCP

https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/
Admin
Forgejo Projects MCP provides Model Context Protocol (MCP) and CLI interfaces for interacting with...
Tokens:31,998
Snippets:357
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install from source

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Install the latest version directly from the GitHub repository.

```bash
uv tool install git+https://github.com/UnwantedForeignCloudProvider/ForgejoProjectsMCP
```

--------------------------------

### Copy .env example file

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/configuration

Command to initialize the .env file from the provided example.

```bash
cp .env.example .env
```

--------------------------------

### Install from local checkout

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Clone the repository and install the tool from the local directory.

```bash
git clone https://github.com/UnwantedForeignCloudProvider/ForgejoProjectsMCP
cd ForgejoProjectsMCP
uv tool install .
```

--------------------------------

### Install from PyPI

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Install the latest release of the tool using uv.

```bash
uv tool install forgejo-projects-mcp
```

--------------------------------

### Verify installation

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Check that the tools are installed and accessible.

```bash
forgejo-projects-mcp --help
forgejo-projects-cli --help
uv tool list
```

--------------------------------

### Verify installation

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Commands to verify the package installation and version reporting.

```bash
uvx --from forgejo-projects-mcp==X.Y.Z forgejo-projects-mcp --help # or: uv tool install forgejo-projects-mcp==X.Y.Z
python -c "import importlib.metadata as m; print(m.version('forgejo-projects-mcp'))"
```

--------------------------------

### Editable installation

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Install the tool in editable mode to make local source edits immediately visible.

```bash
uv tool install --editable .
```

--------------------------------

### Storage state file path examples by OS

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/configuration

Examples of the storage state file path across Linux, macOS, and Windows.

```text
Linux:   ~/.config/forgejo_projects_mcp/storage_state.json
macOS:   ~/.config/forgejo_projects_mcp/storage_state.json
Windows: <home>/.config/forgejo_projects_mcp/storage_state.json
```

--------------------------------

### Sync development dependencies

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Install the locked development dependencies from a local checkout.

```bash
uv sync --dev
```

--------------------------------

### Execute project and repository management commands

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/cli

Examples of common operations including listing repositories, projects, and creating project entities like columns and issues.

```bash
forgejo-projects-cli list_repositories --query kanban
forgejo-projects-cli list_projects --owner o --repo r --state all
forgejo-projects-cli get_project   --owner o --repo r --project_id 3

forgejo-projects-cli create_project --owner o --repo r --title "Q3 Roadmap"
forgejo-projects-cli create_column  --owner o --repo r --project_id 3 --title "To Do"
forgejo-projects-cli create_issue   --owner o --repo r --title "Fix login" --project_id 3

forgejo-projects-cli move_card --owner o --repo r --project_id 3 --column_id 11 \
    --issue_numbers '[5]'
forgejo-projects-cli bulk_move_cards --owner o --repo r --project_id 3 \
    --moves '[{"issue_number":5,"column_id":11},{"issue_number":6,"column_id":12}]'
```

--------------------------------

### Upgrade tool

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Upgrade the installed tool to the latest version.

```bash
uv tool upgrade forgejo-projects-mcp
```

--------------------------------

### CLI usage examples

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/cli

Common commands for interacting with the forgejo-projects-cli, including help, listing projects, and bulk reading issues.

```bash
forgejo-projects-cli --help
forgejo-projects-cli list_projects --owner team --repo platform
forgejo-projects-cli bulk_read_issues \
  --owner team --repo platform --issue_numbers '[1, 2, 3]'

```

--------------------------------

### Run smoke test

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Verify the installation by running the forgejo_status command.

```bash
forgejo-projects-cli forgejo_status
```

--------------------------------

### MCP Tool Error Example

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/usage

Example of an MCP tool failure response indicating a 404 error.

```text
[NOT_FOUND] GET /team/platform/projects/999 -> HTTP 404
```

--------------------------------

### Define main entry point

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/server

The main function calls mcp.run() to start the stdio MCP transport. It is invoked by the package console script forgejo_projects_mcp:main.

```python
def main() -> None
```

--------------------------------

### GET /{owner}/{repo}/projects/{project_id}

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Retrieves the project board data.

```APIDOC
## GET /{owner}/{repo}/projects/{project_id}

### Description
Supplies the board data for a specific project.

### Method
GET

### Endpoint
/{owner}/{repo}/projects/{project_id}

### Parameters
#### Path Parameters
- **owner** (string) - Required - The owner of the repository
- **repo** (string) - Required - The repository name
- **project_id** (string) - Required - The project ID
```

--------------------------------

### GET /repo/search

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Searches for repositories using query parameters.

```APIDOC
## GET /repo/search

### Description
Searches for repositories based on a query string.

### Method
GET

### Endpoint
/repo/search

### Parameters
#### Query Parameters
- **q** (string) - Optional - The search query
- **limit** (integer) - Optional - Limit the number of results
- **page** (integer) - Optional - The page number for pagination
```

--------------------------------

### Update shell integration

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/getting-started

Run this command if the forgejo-projects-mcp command is not found after installation.

```bash
uv tool update-shell
```

--------------------------------

### Get project details with forgejo-projects-cli get_project

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/getting-started

Retrieves project information including column IDs using the project ID.

```bash
forgejo-projects-cli get_project \
  --owner team \
  --repo platform \
  --project_id 12
```

--------------------------------

### GET /user/settings

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Checks the current session status. An HTTP 200 response indicates the user is authenticated.

```APIDOC
## GET /user/settings

### Description
Checks the current session status. Redirects are disabled; an HTTP 200 response indicates the user is authenticated.

### Method
GET

### Endpoint
/user/settings

### Response
#### Success Response (200)
- **Status** (integer) - Indicates successful authentication.
```

--------------------------------

### Run tests and build documentation

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Executes the test suite and builds the documentation to verify the current implementation.

```bash
uv run pytest -q
...................................................................      [100%]

uv run mkdocs build --strict
Documentation built successfully
```

--------------------------------

### Run local entry points

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Execute the local entry points using uv.

```bash
uv run forgejo-projects-mcp --help
uv run forgejo-projects-cli --help
```

--------------------------------

### Discover CLI subcommands and tool options

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/cli

Use the --help flag to list all available subcommands or to view specific options for a single tool.

```bash
forgejo-projects-cli --help          # list every subcommand (tool)
forgejo-projects-cli <tool> --help   # options for one tool
```

--------------------------------

### Preview version

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Command to preview the next-commit version before tagging.

```bash
uvx uv-dynamic-versioning     # e.g. shows the current dev version
```

--------------------------------

### GET /{owner}/{repo}/milestones

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

List milestones for a repository filtered by state.

```APIDOC
## GET /{owner}/{repo}/milestones

### Description
List milestones for a repository, filtered by state.

### Method
GET

### Endpoint
/{owner}/{repo}/milestones

### Parameters
#### Query Parameters
- **state** (string) - Required - Filter by 'open' or 'closed'.
```

--------------------------------

### create_project

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/usage

Creates a new project board.

```APIDOC
## create_project

### Description
Creates a new project in the specified repository.

### Parameters
- **owner** (str) - Required
- **repo** (str) - Required
- **title** (str) - Required
- **description** (str) - Optional - Default: ""
- **card_type** (text|images_and_text) - Optional - Default: text
```

--------------------------------

### Read full project content with pagination

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/cli

Full reader commands like read_project are expensive; use --limit and --offset to manage data retrieval.

```bash
forgejo-projects-cli read_project --owner o --repo r --project_id 3 \
    --state open --limit 20 --offset 0
```

--------------------------------

### Inspecting CLI command options

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/usage

Use the --help flag on a specific command to view its generated options.

```bash
forgejo-projects-cli read_project --help
```

--------------------------------

### Retrieve filtered issues list

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

The client obtains issue numbers from the specified GET endpoint.

```http
GET /{owner}/{repo}/issues?state={open|closed|all}&type=all
```

--------------------------------

### ForgejoClient.ensure

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Ensures an authenticated request context exists by validating credentials, starting Playwright, and performing a login if necessary.

```APIDOC
## async ensure()

### Description
Ensures an authenticated request context exists. It validates credentials, starts Playwright, loads the state file if present, checks user settings, and logs in if needed. Calls are serialized with an async lock.
```

--------------------------------

### List repositories with forgejo-projects-cli list_repositories

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/getting-started

Use this command to identify the owner and repository name by querying the platform.

```bash
forgejo-projects-cli list_repositories --query platform --limit 10 --page 1
```

--------------------------------

### Create a project board with forgejo-projects-cli create_project

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/getting-started

Creates a new project board with a specified title and description.

```bash
forgejo-projects-cli create_project \
  --owner team \
  --repo platform \
  --title "Release board" \
  --description "Work for the next release"
```

--------------------------------

### Quote special characters in .env

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/configuration

Example of quoting values in the .env file that contain shell or dotenv special characters.

```text
FORGEJO_PASSWORD='p@ss$word!'
```

--------------------------------

### Run forgejo-projects-mcp MCP server

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1

The standard entry point for the MCP server.

```bash
forgejo-projects-mcp
```

--------------------------------

### GET /{owner}/{repo}/issues/{issue_number}

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Retrieves the details of a specific issue based on the defined HTML DOM contract.

```APIDOC
## GET /{owner}/{repo}/issues/{issue_number}

### Description
Retrieves the detail page for a specific issue. The parser relies on specific HTML elements to extract the issue number, title, state, body, milestone, and comments.

### Method
GET

### Endpoint
/{owner}/{repo}/issues/{issue_number}

### Parameters
#### Path Parameters
- **owner** (string) - Required - The repository owner.
- **repo** (string) - Required - The repository name.
- **issue_number** (integer) - Required - The issue number.
```

--------------------------------

### Run quality checks

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Execute the repository's quality checks and build process.

```bash
uv run ruff check .
uv run ty check
uv run pytest -q
uv build
```

--------------------------------

### Initialize MCPServer and ForgejoClient

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/server

Initializes the MCP server instance and the Forgejo client used for protocol communication.

```python
mcp = MCPServer("forgejo-projects-mcp", lifespan=_lifespan)
client = ForgejoClient()
```

--------------------------------

### Quality gate execution

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Commands to sync dependencies, run linting, type checking, tests, and build the project. All commands must pass before proceeding.

```bash
uv sync --dev
uv run ruff check .        # lint  — must be clean
uv run ty check            # types — must be clean
uv run pytest -q           # tests — all must pass
uv build                   # must produce dist/*.whl and dist/*.tar.gz
```

--------------------------------

### GET /{owner}/{repo}/issues

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Retrieves a list of issues for a specific repository, supporting filtering by state, type, project, and milestone.

```APIDOC
## GET /{owner}/{repo}/issues

### Description
Retrieves a list of issues from the specified repository. The client can filter results by state, type, project, and milestone.

### Method
GET

### Endpoint
/{owner}/{repo}/issues

### Parameters
#### Query Parameters
- **state** (string) - Optional - Filter by issue state: open, closed, or all.
- **type** (string) - Optional - Filter by issue type.
- **project** (integer) - Optional - Filter by project ID.
- **milestone** (integer) - Optional - Filter by milestone ID.
```

--------------------------------

### GET /{owner}/{repo}/issues/{issue_number}

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Retrieves issue details to resolve a repository-local issue number to a global issue ID.

```APIDOC
## GET /{owner}/{repo}/issues/{issue_number}

### Description
Retrieves the issue page to extract the global `issue_id` required for project board mutations.

### Method
GET

### Endpoint
/{owner}/{repo}/issues/{issue_number}

### Parameters
#### Path Parameters
- **owner** (string) - Required - The repository owner
- **repo** (string) - Required - The repository name
- **issue_number** (integer) - Required - The local issue number
```

--------------------------------

### Documentation build verification

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Command to build the documentation with strict mode enabled to ensure no errors.

```bash
uv run mkdocs build --strict
```

--------------------------------

### List existing projects with forgejo-projects-cli list_projects

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/getting-started

Lists open projects for a specific owner and repository.

```bash
forgejo-projects-cli list_projects --owner team --repo platform --state open
```

--------------------------------

### Resolve issue number to global ID

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Use this GET request to retrieve the global issue_id required for board mutations. The client must extract the data-issue-id attribute from the response.

```http
GET /{owner}/{repo}/issues/{issue_number}
```

--------------------------------

### main()

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/__init__

The main function used to execute the MCP server over stdio.

```APIDOC
## main()

### Description
Runs the stdio MCP server. This is the primary entry point for starting the server process.

### Signature
`main() -> None`
```

--------------------------------

### Run forgejo-projects-cli help

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1

Access the command-line interface for scripts or environments without an MCP transport.

```bash
forgejo-projects-cli --help
```

--------------------------------

### create_project

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Creates a new project in the specified repository.

```APIDOC
## create_project

### Description
Posts a project form and returns the created project details.

### Signature
`async create_project(owner: str, repo: str, title: str, description: str = "", card_type: str = "text") -> dict[str, Any]`

### Parameters
- **owner** (str) - Required
- **repo** (str) - Required
- **title** (str) - Required
- **description** (str) - Optional
- **card_type** (str) - Optional - Maps 'text' to 1 and 'images_and_text' to 2.
```

--------------------------------

### ForgejoClient constructor

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Initializes the client using environment variables for URL and credentials, deferring network activity until an async operation is called.

```python
ForgejoClient()
```

--------------------------------

### Release workflow commands

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

A quick reference for validating the project and performing a release. The validation step includes syncing dependencies, linting, type checking, testing, and building.

```bash
# validate
uv sync --dev && uv run ruff check . && uv run ty check && uv run pytest -q && uv build
# changelog: move Unreleased -> "## [X.Y.Z] - $(date -u +%Y-%m-%d)", commit
# release (after approval)
git tag vX.Y.Z && git push origin vX.Y.Z
```

--------------------------------

### Project lifecycle methods

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Methods to close, reopen, or delete a project.

```python
async close_project(owner, repo, project_id) -> dict[str, Any]
async reopen_project(owner, repo, project_id) -> dict[str, Any]
async delete_project(owner, repo, project_id) -> dict[str, Any]
```

--------------------------------

### POST /{owner}/{repo}/milestones/new

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Create a new milestone.

```APIDOC
## POST /{owner}/{repo}/milestones/new

### Description
Create a new milestone in the repository.

### Method
POST

### Endpoint
/{owner}/{repo}/milestones/new

### Parameters
#### Request Body
- **title** (string) - Required
- **content** (string) - Optional
- **deadline** (string) - Optional - Format: YYYY-MM-DD
```

--------------------------------

### Run tests with custom UV_CACHE_DIR

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Workaround for environments where the default user cache is read-only by pointing the cache to a writable temporary directory.

```bash
UV_CACHE_DIR=/tmp/forgejo-projects-mcp-uv-cache uv run pytest -q
```

--------------------------------

### login method

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Performs an explicit login, optionally forcing a fresh session, and returns authentication details.

```python
async login(force: bool = False) -> dict[str, Any]
```

```json
{
  "authenticated": true,
  "instance": "https://forge.example.com",
  "username": "your-username",
  "state_file": ".../storage_state.json"
}
```

--------------------------------

### Configure Forgejo credentials in .env

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/getting-started

Create a .env file in the working directory to store Forgejo connection details. This file is loaded automatically and should be kept private.

```bash
FORGEJO_URL='https://forge.example.com'
FORGEJO_USERNAME='your-username'
FORGEJO_PASSWORD='your-password'
```

--------------------------------

### POST /{owner}/{repo}/projects/{project_id}

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Creates a new project column.

```APIDOC
## POST /{owner}/{repo}/projects/{project_id}

### Description
Creates a new column in the project.

### Method
POST

### Endpoint
/{owner}/{repo}/projects/{project_id}

### Request Body
- **title** (string) - Required - The title of the column
- **color** (string) - Optional - The hex color string (e.g., #e01e5a)
```

--------------------------------

### create_project method

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Posts a project form and recovers the new project ID.

```python
async create_project(
    owner: str, repo: str, title: str,
    description: str = "", card_type: str = "text",
) -> dict[str, Any]
```

--------------------------------

### get_project method

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Parses the board page to return project details including columns and cards.

```python
async get_project(owner: str, repo: str, project_id: int) -> dict[str, Any]
```

```json
{
    "id": project_id,
    "title": str,
    "columns": [
        {
            "id": int,
            "title": str,
            "cards": [
                {"issue_id": int, "number": int | None, "title": str}
            ],
        }
    ],
}
```

--------------------------------

### Column management methods

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Methods for creating, editing, deleting, and setting default project columns.

```python
async create_column(owner, repo, project_id, title, color: str = "") -> dict[str, Any]
async edit_column(owner, repo, project_id, column_id,
                  title: str | None = None, color: str | None = None) -> dict[str, Any]
async delete_column(owner, repo, project_id, column_id) -> dict[str, Any]
async set_default_column(owner, repo, project_id, column_id) -> dict[str, Any]
```

--------------------------------

### Environment variable documentation verification

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Commands to extract environment variables used in the source code and compare them against the documented variables in .env.example.

```bash
grep -rho "os.environ[.a-zA-Z]*(\?\?\s*\"[A-Z_]*\"" src | grep -o '"[A-Z_]*"' | sort -u
# compare against the keys documented in .env.example
grep -o '^[A-Z_]*' .env.example | sort -u
```

--------------------------------

### Session & Discovery Tools

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/tools

Tools for managing authentication and discovering accessible repositories.

```APIDOC
## forgejo_status
Check authentication status.

## authenticate(force=False)
Log in or refresh the cached session.

## list_repositories(query, limit, page)
List repositories the user can access.
```

--------------------------------

### POST /{owner}/{repo}/projects/{project_id}/{column_id}/default

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Sets a column as the default.

```APIDOC
## POST /{owner}/{repo}/projects/{project_id}/{column_id}/default

### Description
Sets the specified column as the default column for the project.

### Method
POST

### Endpoint
/{owner}/{repo}/projects/{project_id}/{column_id}/default
```

--------------------------------

### list_repositories

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/usage

Lists repositories available to the authenticated user.

```APIDOC
## list_repositories

### Description
Retrieves a list of repositories.

### Parameters
- **query** (str) - Optional - Default: "". Search query.
- **limit** (int) - Optional - Default: 50.
- **page** (int) - Optional - Default: 1.
```

--------------------------------

### list_repositories method

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Requests repository search results and normalizes them into a specific dictionary structure.

```python
async list_repositories(query: str = "", limit: int = 50, page: int = 1) -> list[dict[str, Any]]
```

```json
{
    "full_name": str | None,
    "owner": str,
    "name": str,
    "description": str,
    "private": bool | None,
    "archived": bool | None,
    "empty": bool | None,
    "fork": bool | None,
}
```

--------------------------------

### Tag and push release

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Commands to create an annotated tag and push it to the origin repository.

```bash
git tag vX.Y.Z            # annotated is fine: git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
```

--------------------------------

### main function signature

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/cli

Defines the main entry point for the CLI, handling argument parsing and tool invocation.

```python
main(argv: list[str] | None = None) -> int

```

--------------------------------

### Configuration constants

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Module-level constants defining the configuration directory and state file path.

```python
CONFIG_DIR = <XDG_CONFIG_HOME or Path.home() / ".config"> / "forgejo_projects_mcp"
STATE_FILE = CONFIG_DIR / "storage_state.json"
```

--------------------------------

### Configure Bulk Operation Limits

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/configuration

Adjust FORGEJO_MCP_MAX_CONCURRENCY and FORGEJO_MCP_RPS to reduce load on Forgejo instances or reverse proxies with strict rate limits.

```bash
FORGEJO_MCP_MAX_CONCURRENCY=2
FORGEJO_MCP_RPS=1
```

--------------------------------

### list_projects method

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Returns project entries parsed from the repository projects page, with state validation.

```python
async list_projects(owner: str, repo: str, state: str = "open") -> list[dict[str, Any]]
```

--------------------------------

### get_project

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Retrieves details of a specific project.

```APIDOC
## get_project

### Description
Parses the board page and returns project structure including columns and cards.

### Signature
`async get_project(owner: str, repo: str, project_id: int) -> dict[str, Any]`
```

--------------------------------

### Project tool signatures

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/server

Signatures for tools managing project lifecycle and properties.

```python
async list_projects(owner: str, repo: str, state: str = "open") -> dict
async create_project(owner: str, repo: str, title: str,
                     description: str = "",
                     card_type: str = "text") -> dict
async get_project(owner: str, repo: str, project_id: int) -> dict
async update_project(owner: str, repo: str, project_id: int,
                     title: str | None = None,
                     description: str | None = None,
                     card_type: str | None = None) -> dict
async close_project(owner: str, repo: str, project_id: int) -> dict
async reopen_project(owner: str, repo: str, project_id: int) -> dict
async delete_project(owner: str, repo: str, project_id: int) -> dict
```

--------------------------------

### List of registered MCP tools

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/server

The complete list of 31 tools registered by the server.

```python
forgejo_status, authenticate, list_repositories,
list_projects, create_project, get_project, update_project,
close_project, reopen_project, delete_project,
create_column, edit_column, delete_column, set_default_column,
create_issue, add_issues_to_project, remove_issues_from_project,
move_card, delete_issue,
bulk_move_cards, bulk_read_issues, read_card, read_column,
read_milestone, read_project,
list_milestones, create_milestone, edit_milestone,
close_milestone, reopen_milestone, delete_milestone
```

--------------------------------

### Create and delete issues

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Endpoints for managing issue creation and permanent deletion. Creation supports optional fields like project_id and milestone_id.

```text
Create | POST | /{owner}/{repo}/issues/new | title, content, plus optional project_id, milestone_id, label_ids, assignee_ids
```

```text
Permanently delete | POST | /{owner}/{repo}/issues/{issue_number}/delete | Empty form
```

--------------------------------

### Tool surface documentation verification

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Commands to list available subcommands and tools to ensure they match the documentation.

```bash
uv run forgejo-projects-cli --help            # every subcommand + options
uv run python -c "import asyncio, forgejo_projects_mcp as f; \
  print(sorted(t.name for t in asyncio.run(f.mcp.list_tools())))"
```

--------------------------------

### authenticate

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/usage

Logs in and caches the session.

```APIDOC
## authenticate

### Description
Logs in and caches the session. 

### Parameters
- **force** (bool) - Optional - Default: false. If true, skips the existing cache.
```

--------------------------------

### Project Management Tools

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/tools

Tools for creating, retrieving, and managing project boards.

```APIDOC
## list_projects(owner, repo, state)
## create_project(owner, repo, title, description, card_type)
## get_project(owner, repo, project_id)
## update_project(...)
## close_project(...)
## reopen_project(...)
## delete_project(...)
```

--------------------------------

### __version__

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/__init__

The current version of the package.

```APIDOC
## __version__

### Description
Returns the installed or fallback package version.

### Type
`str`
```

--------------------------------

### AuthError exception

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Raised when credentials are missing or the login session fails to establish.

```python
class AuthError(RuntimeError)
AuthError(message: str, *, code: str = "AUTH_FAILED")
```

--------------------------------

### Session and repository tool signatures

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/server

Signatures for tools related to session status, authentication, and repository listing.

```python
async forgejo_status() -> dict
async authenticate(force: bool = False) -> dict
async list_repositories(query: str = "", limit: int = 50,
                        page: int = 1) -> dict
```

--------------------------------

### ensure method

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Validates credentials and establishes an authenticated request context, using an async lock to serialize calls.

```python
async ensure() -> None
```

--------------------------------

### POST /{owner}/{repo}/milestones/{milestone_id}/open

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Reopen a milestone.

```APIDOC
## POST /{owner}/{repo}/milestones/{milestone_id}/open

### Description
Reopen a specific milestone.

### Method
POST

### Endpoint
/{owner}/{repo}/milestones/{milestone_id}/open

### Parameters
#### Request Body
- **id** (string) - Required - The milestone ID
```

--------------------------------

### Repository state verification commands

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Commands to ensure the repository is on the correct branch, the working tree is clean, and the full history is available.

```bash
git fetch --tags && git status
```

```bash
git status --porcelain
```

```bash
git fetch --tags --unshallow 2>/dev/null; git tag --list | tail
```

--------------------------------

### list_repositories

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Lists repositories based on a search query.

```APIDOC
## list_repositories

### Description
Requests /repo/search and returns a list of normalized repository objects.

### Signature
`async list_repositories(query: str = "", limit: int = 50, page: int = 1) -> list[dict[str, Any]]`

### Parameters
- **query** (str) - Optional - Search query string.
- **limit** (int) - Optional - Number of results to return.
- **page** (int) - Optional - Page number.

### Response
- **full_name** (str | None)
- **owner** (str)
- **name** (str)
- **description** (str)
- **private** (bool | None)
- **archived** (bool | None)
- **empty** (bool | None)
- **fork** (bool | None)
```

--------------------------------

### Column Management

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/client

Methods for managing project columns.

```APIDOC
## Column Management

### Methods
- `create_column(owner, repo, project_id, title, color: str = "")`
- `edit_column(owner, repo, project_id, column_id, title: str | None = None, color: str | None = None)`
- `delete_column(owner, repo, project_id, column_id)`
- `set_default_column(owner, repo, project_id, column_id)`
```

--------------------------------

### Commit release changes

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/RELEASING

Command to commit the updated changelog and documentation files.

```bash
git add CHANGELOG.md README.md .env.example .claude docs && git commit -m "chore: release X.Y.Z"
```

--------------------------------

### Column tool signatures

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/server

Signatures for tools managing project columns.

```python
async create_column(owner: str, repo: str, project_id: int,
                    title: str, color: str = "") -> dict
async edit_column(owner: str, repo: str, project_id: int, column_id: int,
                  title: str | None = None,
                  color: str | None = None) -> dict
async delete_column(owner: str, repo: str, project_id: int,
                    column_id: int) -> dict
async set_default_column(owner: str, repo: str, project_id: int,
                         column_id: int) -> dict
```

--------------------------------

### Reinstall non-editable tool

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/installation

Reinstall the tool after changing the checkout or switching commits.

```bash
uv tool install . --force
```

--------------------------------

### Import server and mcp

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/reference/__init__

Imports the main server function and the mcp server object from the server module.

```python
from .server import main, mcp
```

--------------------------------

### POST /user/login

Source: https://unwantedforeigncloudprovider.github.io/ForgejoProjectsMCP/0.1.0rc1/forgejo-projects-automation-reference

Authenticates a user session using credentials.

```APIDOC
## POST /user/login

### Description
Logs in a user. Login redirects are disabled. A redirect status (301, 302, 303, 307, or 308) is treated as success.

### Method
POST

### Endpoint
/user/login

### Request Body
- **user_name** (string) - Required - The username for authentication
- **password** (string) - Required - The password for authentication
- **remember** (string) - Optional - Set to 'on' to remember the session
```
Tokens:
Raw