### 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.
```

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

### 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'.
```

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

### 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.
```

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

### 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
```

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

### 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!'
```

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

### 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.
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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"
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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()
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### Version determination

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

Command to check the current version based on tags.

```bash
git describe --tags
```

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

### Create an issue on a board with forgejo-projects-cli create_issue

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

Creates an issue and assigns it to a project board in one operation.

```bash
forgejo-projects-cli create_issue \
  --owner team \
  --repo platform \
  --title "Prepare release notes" \
  --body "Document the changes before tagging." \
  --project_id 12
```

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

### reopen_project

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

Reopens an archived project.

```APIDOC
## reopen_project

### Description
Reopens an archived project.

### Parameters
- **owner** (str) - Required
- **repo** (str) - Required
- **project_id** (int) - Required
```

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

### status method

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

Returns authenticated session information, catching and converting errors into a dictionary format.

```python
async status() -> dict[str, Any]
```

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

### mcp

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

The registered MCPServer object instance.

```APIDOC
## mcp

### Description
The registered server object, useful for introspection and testing purposes.

### Type
`MCPServer`
```

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

### Generate UTC date

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

Command to generate the current UTC date for the release heading.

```bash
date -u +%Y-%m-%d
```

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

### Create a project column with forgejo-projects-cli create_column

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

Adds a new column to an existing project board with a specific title and color.

```bash
forgejo-projects-cli create_column \
  --owner team \
  --repo platform \
  --project_id 12 \
  --title "In progress" \
  --color '#e01e5a'
```

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

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

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

Creates a new issue in the repository.

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

### Description
Creates a new issue with optional project, milestone, label, and assignee associations.

### Method
POST

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

### Parameters
#### Request Body
- **title** (string) - Required
- **content** (string) - Required
- **project_id** (integer) - Optional
- **milestone_id** (integer) - Optional
- **label_ids** (string) - Optional - Comma-separated IDs
- **assignee_ids** (string) - Optional - Comma-separated IDs
```

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

### read_project

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

Reads a project.

```APIDOC
## read_project(owner: str, repo: str, project_id: int, state: str = "all", milestone: int | None = None, limit: int | None = None, offset: int = 0) -> dict

### Description
Retrieves details for a specific project.

### Parameters
- **owner** (str) - Required - The owner of the repository.
- **repo** (str) - Required - The name of the repository.
- **project_id** (int) - Required - The project ID.
- **state** (str) - Optional - Filter by state (default: "all").
- **milestone** (int) - Optional - Filter by milestone ID.
- **limit** (int) - Optional - Result limit.
- **offset** (int) - Optional - Result offset (default: 0).
```

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

### list_projects

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

Retrieves a list of projects for a specific repository.

```APIDOC
## list_projects

### Description
Returns project entries parsed from the repository projects page.

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

### Parameters
- **owner** (str) - Required - Repository owner.
- **repo** (str) - Required - Repository name.
- **state** (str) - Optional - Project state (open, closed, all).
```

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

### System Architecture Diagram

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

Visual representation of the data flow between the MCP client, server, ForgejoClient, and the Forgejo web routes.

```text
MCP client ──stdio──> server.py ──> ForgejoClient ──Playwright HTTP──> Forgejo web routes
                           │              │
                           │              ├── session cookie cache
                           │              ├── HTML parsing / ID recovery
                           │              └── throttling and retries
                           │
CLI ──generated argparse───┘
```

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

### create_milestone

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

Creates a new milestone.

```APIDOC
## create_milestone(owner: str, repo: str, title: str, description: str = "", deadline: str = "") -> dict

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

### Parameters
- **owner** (str) - Required - The owner of the repository.
- **repo** (str) - Required - The name of the repository.
- **title** (str) - Required - The title of the milestone.
- **description** (str) - Optional - Milestone description.
- **deadline** (str) - Optional - Milestone deadline.
```

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

### create_column

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

Creates a new column in a project.

```APIDOC
## create_column

### Description
Adds a new column to the project.

### Parameters
- **owner** (str) - Required
- **repo** (str) - Required
- **project_id** (int) - Required
- **title** (str) - Required
- **color** (str) - Optional - Default: ""
```

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

### Register MCP server in JSON configuration

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

Use this generic JSON structure to register the MCP server in your client's local-server configuration. Replace the environment variables with your specific Forgejo instance details and avoid committing credentials to version control.

```json
{
  "mcpServers": {
    "forgejo-projects-mcp": {
      "command": "forgejo-projects-mcp",
      "env": {
        "FORGEJO_URL": "https://forge.example.com",
        "FORGEJO_USERNAME": "your-username",
        "FORGEJO_PASSWORD": "your-password"
      }
    }
  }
}
```

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

### Uninstall tool

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

Remove the tool from the system.

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

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

### Force fresh authentication via CLI

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

If your password has changed but the session remains active, use this command to force a fresh login.

```bash
forgejo-projects-cli authenticate --force true
```

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

### ForgejoClient.login

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

Performs an explicit login to the Forgejo instance.

```APIDOC
## async login(force: bool = False)

### Description
Performs an explicit login and returns session information. If force is set to True, the existing request context or cache is ignored and a fresh login is performed.

### Parameters
- **force** (bool) - Optional - If True, ignores existing cache and forces a fresh login.
```

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

### Milestone management methods

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

Methods for listing, creating, editing, closing, reopening, and deleting milestones.

```python
async list_milestones(owner, repo, state: str = "open") -> list[dict[str, Any]]
async create_milestone(owner, repo, title, description: str = "",
                       deadline: str = "") -> dict[str, Any]
async edit_milestone(owner, repo, milestone_id, title: str | None = None,
                     description: str | None = None,
                     deadline: str | None = None) -> dict[str, Any]
async close_milestone(owner, repo, milestone_id) -> dict[str, Any]
async reopen_milestone(owner, repo, milestone_id) -> dict[str, Any]
async delete_milestone(owner, repo, milestone_id) -> dict[str, Any]
```

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

### Define public exports

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

Defines the public interface of the package using __all__.

```python
__all__ = ["__version__", "main", "mcp"]
```

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

### Storage state file path

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

The default location for the authenticated Playwright storage state file.

```text
<config>/forgejo_projects_mcp/storage_state.json
```

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

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

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

Moves or reorders cards within a project column.

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

### Description
Updates the position of issues within a specific project column.

### Method
POST

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

### Parameters
#### Request Body
- **issues** (array) - Required - List of objects containing issueID and sorting index
```

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

### close_project / reopen_project / delete_project

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

Changes the state of a project or deletes it.

```APIDOC
## close_project / reopen_project / delete_project

### Description
Performs state transitions on a project.

### Signatures
`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]`
```

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

### list_milestones

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

Lists milestones for a repository.

```APIDOC
## list_milestones(owner: str, repo: str, state: str = "open") -> dict

### Description
Lists all milestones for the given repository, returning a count and the list of milestones.

### Parameters
- **owner** (str) - Required - The owner of the repository.
- **repo** (str) - Required - The name of the repository.
- **state** (str) - Optional - Filter by state (default: "open").
```

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

### Issue and Card Management

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

Tools for managing issues and their placement on project boards.

```APIDOC
## create_issue(... project_id=)
## add_issues_to_project
## remove_issues_from_project
## move_card(owner, repo, project_id, column_id, issue_numbers)
## bulk_move_cards(owner, repo, project_id, moves)
## delete_issue
```

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

### Successful authentication JSON output

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

The expected JSON output when the authentication is successful.

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

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

### Issue management methods

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

Methods for creating and deleting issues.

```python
async create_issue(
    owner, repo, title, body: str = "", project_id: int | None = None,
    milestone_id: int | None = None, label_ids: list[int] | None = None,
    assignee_ids: list[int] | None = None,
) -> dict[str, Any]
async delete_issue(owner, repo, number) -> dict[str, Any]
```

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

### Forgejo Project and Column Repository Paths

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

Repository paths used to access Forgejo Projects and Kanban columns via web routes.

```text
/{owner}/{repo}/projects
/{owner}/{repo}/projects/{project_id}
```

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

### Enable Debug Logging for CLI

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

Set the FORGEJO_MCP_LOG_LEVEL environment variable to DEBUG to troubleshoot request and parsing behavior in the CLI.

```bash
FORGEJO_MCP_LOG_LEVEL=DEBUG forgejo-projects-cli forgejo_status
```

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

### Project creation form data

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

The payload structure required for creating a new project, where card_type 1 represents text and 2 represents images and text.

```text
redirect=
title={title}
content={description}
template_type=
card_type=1|2

```

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

### Read issue summaries efficiently

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

Use bulk_read_issues for lightweight summaries to minimize costs compared to full reader commands.

```bash
forgejo-projects-cli bulk_read_issues --owner o --repo r --issue_numbers '[5,6,7]'
```

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

### Issue and card tool signatures

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

Signatures for tools managing issues and cards within projects.

```python
async create_issue(owner: str, repo: str, title: str, body: str = "",
                   project_id: int | None = None,
                   milestone_id: int | None = None,
                   label_ids: list[int] | None = None,
                   assignee_ids: list[int] | None = None) -> dict
async add_issues_to_project(owner: str, repo: str, project_id: int,
                            issue_numbers: list[int]) -> dict
async remove_issues_from_project(owner: str, repo: str,
                                 issue_numbers: list[int]) -> dict
async move_card(owner: str, repo: str, project_id: int, column_id: int,
                issue_numbers: list[int]) -> dict
async delete_issue(owner: str, repo: str, number: int) -> dict
```

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

### build_parser function signature

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

Defines the function signature for building the root parser and subcommands based on tool definitions.

```python
build_parser(tools) -> argparse.ArgumentParser

```

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

### DELETE /{owner}/{repo}/projects/{project_id}/{column_id}

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

Deletes a project column.

```APIDOC
## DELETE /{owner}/{repo}/projects/{project_id}/{column_id}

### Description
Deletes a specific project column. Note that the default column cannot be deleted.

### Method
DELETE

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

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

### Bulk move cards method

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

Moves cards in bulk, grouping by column and executing requests concurrently.

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

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

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

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

Edit an existing milestone.

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

### Description
Edit an existing milestone. Note: Omitted arguments become empty strings.

### Method
POST

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

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

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

### Define _safe execution wrapper

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

Runs client coroutines while catching expected errors and converting them to ToolError.

```python
async _safe(coro: Awaitable) -> Any
```

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

### Bulk and content reader methods

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

Asynchronous methods for bulk operations and reading project content. Note that bulk_read_issues separates failures into an errors field, and the four full readers are marked as expensive.

```python
async bulk_move_cards(owner: str, repo: str, project_id: int,
                      moves: list[dict[str, int]]) -> dict
async bulk_read_issues(owner: str, repo: str,
                       issue_numbers: list[int],
                       state: str = "all") -> dict
async read_card(owner: str, repo: str, number: int) -> dict
async read_column(owner: str, repo: str, project_id: int, column_id: int,
                  state: str = "all", milestone: int | None = None,
                  limit: int | None = None, offset: int = 0) -> dict
async read_milestone(owner: str, repo: str, milestone_id: int,
                     state: str = "all", project: int | None = None,
                     limit: int | None = None, offset: int = 0) -> dict
async read_project(owner: str, repo: str, project_id: int,
                   state: str = "all", milestone: int | None = None,
                   limit: int | None = None, offset: int = 0) -> dict
```

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

### close_project

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

Archives a project.

```APIDOC
## close_project

### Description
Archives the project.

### Parameters
- **owner** (str) - Required
- **repo** (str) - Required
- **project_id** (int) - Required
```

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

### PUT /{owner}/{repo}/projects/{project_id}/{column_id}

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

Edits an existing project column.

```APIDOC
## PUT /{owner}/{repo}/projects/{project_id}/{column_id}

### Description
Updates the title and/or color of an existing project column.

### Method
PUT

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

### Request Body
- **title** (string) - Optional - The new title
- **color** (string) - Optional - The new hex color string
```

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

### load_env function signature

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

The load_env function signature as defined in the module.

```python
load_env() -> None

```

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

### _invoke function signature

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

Defines the asynchronous function for calling MCP tools and handling errors.

```python
async _invoke(name: str, arguments: dict) -> tuple[str, bool]

```