coala-client

如何使用 colona-client CLI 与 LLM、MCP 服务器和技能聊天。当用户询问如何使用 colona、运行 colona 聊天、添加 MCP 服务器、导入 CWL 工具集、列出或调用 MCP 工具或者导入或加载技能时使用。

# Coala Client

Part of the coala ecosystem. CLI for chat with OpenAI-compatible LLMs (OpenAI, Gemini, Ollama) and MCP (Model Context Protocol) servers. Supports importing CWL toolsets as MCP servers, importing skills.

## Config paths

- MCP config and toolsets: `~/.config/coala/mcps/`  
  - `mcp_servers.json` — server definitions  
  - `<toolset>/` — per-toolset dirs with `run_mcp.py` and CWL files  
- Skills: `~/.config/coala/skills/` (one subfolder per imported source)  
- Env: `~/.config/coala/env` (optional; key=value for providers and MCP env)

## Quick start

1. **Init (first time)**  
   `coala init` — creates `~/.config/coala/mcps/mcp_servers.json` and `env`.

2. **Set API key**  
   e.g. `export OPENAI_API_KEY=...` or `export GEMINI_API_KEY=...`. Ollama needs no key.

3. **Chat**  
   `coala` or `coala chat` — interactive chat with MCP tools.  
   `coala ask "question"` — single prompt with MCP.

4. **Options**  
   `-p, --provider` (openai|gemini|ollama|custom), `-m, --model`, `--no-mcp`.

## MCP: CWL toolsets

No API key needed for MCP import, list, or call — only for chat/ask with an LLM.

- **Import** (creates toolset under `~/.config/coala/mcps/<TOOLSET>/` and registers server):  
  `coala mcp-import <TOOLSET> <SOURCES...>` or alias `coala mcp ...`  
  SOURCES: local `.cwl` files, a `.zip`, or http(s) URLs to a .cwl or .zip.  
  Requires the `coala` package where the MCP server runs (for `run_mcp.py`).

- **List**  
  `coala mcp-list` — list server names.  
  `coala mcp-list <SERVER_NAME>` — print each tool’s schema (name, description, inputSchema).

- **Call**  
  `coala mcp-call <SERVER>.<TOOL> --args '<JSON>'`  
  Example: `coala mcp-call gene-variant.ncbi_datasets_gene --args '{"data": [{"gene": "TP53", "taxon": "human"}]}'`

## Skills

- **Import** (into `~/.config/coala/skills/`, one subfolder per source):  
  `coala skill <SOURCES...>`  
  SOURCES: GitHub tree URL (e.g. `https://github.com/owner/repo/tree/main/skills`), zip URL, or local zip/dir.

- **In chat**  
  `/skill` — list installed skills.  
  `/skill <name>` — load skill from `~/.config/coala/skills/<name>/` (e.g. SKILL.md) into context.


## Chat commands

- `/help`, `/exit`, `/quit`, `/clear`  
- `/tools` — list MCP tools  
- `/servers` — list connected MCP servers  
- `/skill` — list skills; `/skill <name>` — load a skill  
- `/model` — show model info  
- `/switch <provider>` — switch provider  

## MCP on/off

- **All off:** `coala --no-mcp` (or `coala ask "..." --no-mcp`).  
- **One server off:** remove its entry from `~/.config/coala/mcps/mcp_servers.json`.  
- **On:** default when `--no-mcp` is not used; add or restore servers in `mcp_servers.json`.

## Providers and env

Set provider via `-p` or env `PROVIDER`. Set keys and URLs per provider (e.g. `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OLLAMA_BASE_URL`). Optional: put vars in `~/.config/coala/env`.  
`coala config` — print current config paths and provider/model info.

---

## 中文说明

# Coala Client

coala 生态系统的一部分。用于与 OpenAI 兼容的 LLM（OpenAI、Gemini、Ollama）和 MCP（Model Context Protocol）服务器聊天的 CLI。支持将 CWL 工具集导入为 MCP 服务器，以及导入技能。

## 配置路径

- MCP 配置和工具集：`~/.config/coala/mcps/`  
  - `mcp_servers.json` — 服务器定义  
  - `<toolset>/` — 每个工具集的目录，包含 `run_mcp.py` 和 CWL 文件  
- 技能：`~/.config/coala/skills/`（每个导入的来源对应一个子文件夹）  
- 环境变量：`~/.config/coala/env`（可选；为各提供商和 MCP 环境配置 key=value）

## 快速开始

1. **初始化（首次）**  
   `coala init` — 创建 `~/.config/coala/mcps/mcp_servers.json` 和 `env`。

2. **设置 API 密钥**  
   例如 `export OPENAI_API_KEY=...` 或 `export GEMINI_API_KEY=...`。Ollama 无需密钥。

3. **聊天**  
   `coala` 或 `coala chat` — 带 MCP 工具的交互式聊天。  
   `coala ask "question"` — 带 MCP 的单次提示。

4. **选项**  
   `-p, --provider`（openai|gemini|ollama|custom）、`-m, --model`、`--no-mcp`。

## MCP：CWL 工具集

MCP 的导入、列出或调用不需要 API 密钥 —— 只有与 LLM 进行 chat/ask 时才需要。

- **导入**（在 `~/.config/coala/mcps/<TOOLSET>/` 下创建工具集并注册服务器）：  
  `coala mcp-import <TOOLSET> <SOURCES...>` 或别名 `coala mcp ...`  
  SOURCES：本地 `.cwl` 文件、一个 `.zip`，或指向 .cwl 或 .zip 的 http(s) URL。  
  需要在运行 MCP 服务器的位置安装 `coala` 包（用于 `run_mcp.py`）。

- **列出**  
  `coala mcp-list` — 列出服务器名称。  
  `coala mcp-list <SERVER_NAME>` — 打印每个工具的 schema（name、description、inputSchema）。

- **调用**  
  `coala mcp-call <SERVER>.<TOOL> --args '<JSON>'`  
  示例：`coala mcp-call gene-variant.ncbi_datasets_gene --args '{"data": [{"gene": "TP53", "taxon": "human"}]}'`

## 技能

- **导入**（导入到 `~/.config/coala/skills/`，每个来源对应一个子文件夹）：  
  `coala skill <SOURCES...>`  
  SOURCES：GitHub tree URL（例如 `https://github.com/owner/repo/tree/main/skills`）、zip URL，或本地 zip/目录。

- **在聊天中**  
  `/skill` — 列出已安装的技能。  
  `/skill <name>` — 从 `~/.config/coala/skills/<name>/`（例如 SKILL.md）加载技能到上下文中。


## 聊天命令

- `/help`、`/exit`、`/quit`、`/clear`  
- `/tools` — 列出 MCP 工具  
- `/servers` — 列出已连接的 MCP 服务器  
- `/skill` — 列出技能；`/skill <name>` — 加载某个技能  
- `/model` — 显示模型信息  
- `/switch <provider>` — 切换提供商  

## MCP 开/关

- **全部关闭：** `coala --no-mcp`（或 `coala ask "..." --no-mcp`）。  
- **关闭单个服务器：** 从 `~/.config/coala/mcps/mcp_servers.json` 中删除其条目。  
- **开启：** 未使用 `--no-mcp` 时为默认状态；在 `mcp_servers.json` 中添加或恢复服务器。

## 提供商与环境变量

通过 `-p` 或环境变量 `PROVIDER` 设置提供商。为各提供商设置密钥和 URL（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY`、`OLLAMA_BASE_URL`）。可选：将变量放入 `~/.config/coala/env`。  
`coala config` — 打印当前配置路径以及提供商/模型信息。