Metadata-Version: 2.5
Name: cyborg-mcp-servers
Version: 0.1.2
Summary: MCP servers for the Cyborg ecosystem: Argo/Kubernetes troubleshooting (argo-k8s) and organizational-data queries (orgdata). Primarily for internal Red Hat / openshift-eng use.
Project-URL: Homepage, https://github.com/openshift-eng/cyborg-mcp-servers
Project-URL: Repository, https://github.com/openshift-eng/cyborg-mcp-servers
Project-URL: Changelog, https://github.com/openshift-eng/cyborg-mcp-servers/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/openshift-eng/cyborg-mcp-servers/issues
Author-email: Eris Hoxha <ehoxha@redhat.com>
Maintainer-email: Eris Hoxha <ehoxha@redhat.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-tools,argo,kubernetes,mcp,model-context-protocol,organizational-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio~=4.9
Requires-Dist: click>=8.0.0
Requires-Dist: mcp==1.27.1
Requires-Dist: pydantic-settings~=2.9
Requires-Dist: pydantic~=2.11
Provides-Extra: all
Requires-Dist: google-cloud-storage>=2.0.0; extra == 'all'
Requires-Dist: kubernetes<37,>=35; extra == 'all'
Requires-Dist: orgdatacore<3,>=2.0; extra == 'all'
Requires-Dist: rapidfuzz>=3.0.0; extra == 'all'
Requires-Dist: starlette>=0.37.0; extra == 'all'
Requires-Dist: uvicorn>=0.29.0; extra == 'all'
Provides-Extra: argo
Requires-Dist: kubernetes<37,>=35; extra == 'argo'
Provides-Extra: dev
Requires-Dist: mypy<2.0,>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Requires-Dist: ruff<0.9,>=0.6; extra == 'dev'
Provides-Extra: gcs
Requires-Dist: google-cloud-storage>=2.0.0; extra == 'gcs'
Provides-Extra: http
Requires-Dist: starlette>=0.37.0; extra == 'http'
Requires-Dist: uvicorn>=0.29.0; extra == 'http'
Provides-Extra: orgdata
Requires-Dist: orgdatacore<3,>=2.0; extra == 'orgdata'
Requires-Dist: rapidfuzz>=3.0.0; extra == 'orgdata'
Description-Content-Type: text/markdown

# Cyborg MCP Servers

[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers for the
Cyborg ecosystem, packaged as a single installable distribution with per-server
extras. Usable standalone with Claude Code, Cursor, and other MCP clients, and
programmatically in-process by other Python hosts.

## Servers

| Server | Console script | Extra | Docs |
|--------|----------------|-------|------|
| **argo-k8s** — Argo Workflows / Kubernetes / Argo CD / Peribolos troubleshooting | `argo-k8s-mcp` | `[argo]` | [docs/argo-k8s.md](docs/argo-k8s.md) |
| **orgdata** — organizational data queries (employees, teams, orgs, Jira ownership) | `orgdata-mcp-server` | `[orgdata]`, `[gcs]` | [docs/orgdata.md](docs/orgdata.md) |

Both servers' code ships in every install; the **extras gate dependencies, not
modules**. A server whose extra is missing errors with a friendly hint (e.g.
`install 'cyborg-mcp-servers[argo]'`) instead of a raw `ImportError`.

## Install

Requires Python 3.11+. Tagged releases publish to PyPI (via Trusted Publishing);
you can also install from a GitHub Release asset or directly from git. (The first
PyPI publish needs a one-time project + Trusted Publisher setup — see
[RELEASING.md](RELEASING.md).)

```bash
# Both servers, all transports and data sources:
uv pip install "cyborg-mcp-servers[all] @ git+https://github.com/openshift-eng/cyborg-mcp-servers"

# Just one server:
uv pip install "cyborg-mcp-servers[argo] @ git+https://github.com/openshift-eng/cyborg-mcp-servers"
uv pip install "cyborg-mcp-servers[orgdata,gcs] @ git+https://github.com/openshift-eng/cyborg-mcp-servers"
```

Extras: `argo`, `orgdata`, `gcs` (orgdata GCS data source), `http` (streamable-HTTP
transport; also ships transitively with `mcp`), `dev`, and `all`
(= `argo,orgdata,gcs,http`).

## Run

```bash
argo-k8s-mcp                 # stdio (default); or: argo-k8s-mcp http --port 8080
orgdata-mcp-server stdio     # or: orgdata-mcp-server http --port 8000
```

### Client configuration (`.mcp.json`)

```json
{
  "mcpServers": {
    "argo-k8s": {
      "type": "stdio",
      "command": "argo-k8s-mcp",
      "env": { "ARGO_MCP_KUBECONFIG_CONTEXT": "your-cluster-context" }
    },
    "orgdata": {
      "type": "stdio",
      "command": "orgdata-mcp-server",
      "args": ["stdio"],
      "env": {
        "ORGDATA_GCS_BUCKET": "resolved-org",
        "ORGDATA_GCS_OBJECT_PATH": "orgdata/comprehensive_index_dump.json",
        "ORGDATA_GCS_PROJECT_ID": "openshift-crt"
      }
    }
  }
}
```

See each server's doc for the full configuration reference.

## In-process use

`argo-k8s` exposes its tools as an importable library for agent frameworks — see
`argo_k8s_mcp.api` and [docs/argo-k8s.md](docs/argo-k8s.md). `orgdata` is best
consumed in-process via its underlying library,
[`orgdatacore`](https://github.com/openshift-eng/cyborg-data), rather than the MCP
server.

## Development

```bash
make install-dev    # uv sync with all extras + dev tooling
make all            # lint + format-check + typecheck + test (the CI gate)
make test           # pytest (both suites, under tests/)
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [RELEASING.md](RELEASING.md).

## Layout

```
cyborg-mcp-servers/
├── pyproject.toml          # one package, per-server extras, hatch-vcs version
├── src/
│   ├── argo_k8s_mcp/       # argo-k8s server + in-process api
│   └── orgdata_mcp/        # orgdata server
├── tests/{argo_k8s,orgdata}/
├── deploy/argo-k8s/        # RBAC manifests for in-cluster deployment
├── scripts/                # cluster setup helpers
└── docs/                   # per-server references
```
