Metadata-Version: 2.4
Name: starbridge
Version: 0.0.86
Summary: ⭐ Integrates Claude Desktop with the web, Google and Atlassian workspaces.
Project-URL: Homepage, https://starbridge.readthedocs.io/en/latest/
Project-URL: Documentation, https://starbridge.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/helmut-hoffer-von-ankershoffen/starbridge
Project-URL: Changelog, https://github.com/helmut-hoffer-von-ankershoffen/starbridge/releases
Project-URL: Issues, https://github.com/helmut-hoffer-von-ankershoffen/starbridge/issues
Author-email: Helmut Hoffer von Ankershoffen <helmuthva@googlemail.com>
License: MIT License
        
        Copyright (c) [2025] [Helmut Hoffer von Ankershoffen (helmuthva@googlemail.com)]
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: anthropic,atlassian,bump-my-version,claude,codecov,confluence,cyclonedx,devcontainer,docker,docker-compose,git-cliff,github-actions,google-drive,jira,logfire,mcp,nox,opentelemetry,pre-commit,pydantic,pytest,pytest-asyncio,pytest-cov,pytest-docker,pytest-env,pytest-xdist,renovate,ruff,sonarqube,typer,uv
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: OpenTelemetry :: Instrumentations
Classifier: Framework :: Pydantic
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
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: <4.0,>=3.11
Requires-Dist: atlassian-python-api>=3.41.19
Requires-Dist: beautifulsoup4>=4.13.3
Requires-Dist: brave-search-python-client>=0.3.12
Requires-Dist: cryptography>=44.0.1
Requires-Dist: email-validator>=2.2.0
Requires-Dist: enum-tools>=0.12.0
Requires-Dist: griffe>=1.5.7
Requires-Dist: logfire[system-metrics]>=3.6.4
Requires-Dist: markdown>=3.7
Requires-Dist: markdownify>=1.0.0
Requires-Dist: markitdown>=0.0.2
Requires-Dist: mcp==1.3.0
Requires-Dist: opentelemetry-api>=1.30.0
Requires-Dist: opentelemetry-instrumentation-httpx>=0.50b0
Requires-Dist: opentelemetry-instrumentation-requests>=0.50b0
Requires-Dist: opentelemetry-instrumentation-sqlite3>=0.50b0
Requires-Dist: opentelemetry-instrumentation-starlette>=0.50b0
Requires-Dist: opentelemetry-instrumentation-urllib3>=0.50b0
Requires-Dist: opentelemetry-instrumentation-urllib>=0.50b0
Requires-Dist: opentelemetry-instrumentation>=0.50b0
Requires-Dist: protego>=0.4.0
Requires-Dist: pydantic-settings>=2.8.1
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pymupdf4llm>=0.0.17
Requires-Dist: pymupdf==1.25.3
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: readabilipy>=0.3.0
Requires-Dist: sphinx-toolbox>=3.8.3
Requires-Dist: strip-markdown>=1.3
Requires-Dist: typer>=0.15.2
Provides-Extra: examples
Requires-Dist: jinja2>=3.1.6; extra == 'examples'
Requires-Dist: jupyter>=1.1.1; extra == 'examples'
Requires-Dist: marimo>=0.11.19; extra == 'examples'
Requires-Dist: streamlit>=1.43.2; extra == 'examples'
Provides-Extra: imaging
Requires-Dist: cairosvg>=2.7.1; extra == 'imaging'
Requires-Dist: svglib>=1.5.1; extra == 'imaging'
Description-Content-Type: text/markdown

# ⭐ Starbridge

[![License](https://img.shields.io/github/license/helmut-hoffer-von-ankershoffen/starbridge?logo=opensourceinitiative&logoColor=3DA639&labelColor=414042&color=A41831)
](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/LICENSE)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/starbridge.svg?logo=python&color=204361&labelColor=1E2933)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/noxfile.py)
[![CI](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/actions/workflows/test-and-report.yml/badge.svg)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/actions/workflows/test-and-report.yml)
[![Read the Docs](https://img.shields.io/readthedocs/starbridge)](https://starbridge.readthedocs.io/en/latest/)
[![CodeQL](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/actions/workflows/codeql.yml/badge.svg)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/security/code-scanning)
[![Dependabot](https://img.shields.io/badge/dependabot-active-brightgreen?style=flat-square&logo=dependabot)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/security/dependabot)
[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
[![Security](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
[![Maintainability](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
[![Coverage](https://codecov.io/gh/helmut-hoffer-von-ankershoffen/starbridge/graph/badge.svg?token=SX34YRP30E)](https://codecov.io/gh/helmut-hoffer-von-ankershoffen/starbridge)
[![Ruff](https://img.shields.io/badge/style-Ruff-blue?color=D6FF65)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/noxfile.py)
[![MyPy](https://img.shields.io/badge/mypy-checked-blue)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/noxfile.py)
[![GitHub - Version](https://img.shields.io/github/v/release/helmut-hoffer-von-ankershoffen/starbridge?label=GitHub&style=flat&labelColor=1C2C2E&color=blue&logo=GitHub&logoColor=white)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/releases)
[![GitHub - Commits](https://img.shields.io/github/commit-activity/m/helmut-hoffer-von-ankershoffen/starbridge/main?label=commits&style=flat&labelColor=1C2C2E&color=blue&logo=GitHub&logoColor=white)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/commits/main/)
[![PyPI - Version](https://img.shields.io/pypi/v/starbridge.svg?label=PyPI&logo=pypi&logoColor=%23FFD243&labelColor=%230073B7&color=FDFDFD)](https://pypi.python.org/pypi/starbridge)
[![PyPI - Status](https://img.shields.io/pypi/status/starbridge?logo=pypi&logoColor=%23FFD243&labelColor=%230073B7&color=FDFDFD)](https://pypi.python.org/pypi/starbridge)
[![Docker - Version](https://img.shields.io/docker/v/helmuthva/starbridge?sort=semver&label=Docker&logo=docker&logoColor=white&labelColor=1354D4&color=10151B)](https://hub.docker.com/r/helmuthva/starbridge/tags)
[![Docker - Size](https://img.shields.io/docker/image-size/helmuthva/starbridge?sort=semver&arch=arm64&label=image&logo=docker&logoColor=white&labelColor=1354D4&color=10151B)](https://hub.docker.com/r/helmuthva/starbridge/)
[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template)
[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/helmut-hoffer-von-ankershoffen/starbridge)
[![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/helmut-hoffer-von-ankershoffen/starbridge)

<!---
[![ghcr.io - Version](https://ghcr-badge.egpl.dev/helmut-hoffer-von-ankershoffen/starbridge/tags?color=%2344cc11&ignore=0.0%2C0%2Clatest&n=3&label=ghcr.io&trim=)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/pkgs/container/starbridge)
[![ghcr.io - Sze](https://ghcr-badge.egpl.dev/helmut-hoffer-von-ankershoffen/starbridge/size?color=%2344cc11&tag=latest&label=size&trim=)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/pkgs/container/starbridge)
-->

> [!TIP]
> 📚 [Online documentation](https://starbridge.readthedocs.io/en/latest/) - 📖 [PDF Manual](https://starbridge.readthedocs.io/_/downloads/en/latest/pdf/)

> [!NOTE]
> 🧠 This project was scaffolded using the template [oe-python-template](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template) with [copier](https://copier.readthedocs.io/).

---


Integrates Claude Desktop with the web, Google and Atlassian workspaces.

Use Cases:
1) Fast and easy to use project setup
2) Consistent update of already scaffolded projects to benefit from new and improved features.
3) Dummy CLI application and service demonstrating example usage of the generated directory structure and build pipeline

## Scaffolding

**Step 1**: Install uv package manager and copier
```shell
if [[ "$OSTYPE" == "darwin"* ]]; then                 # Install dependencies for macOS X
  if ! command -v brew &> /dev/null; then             ## Install Homebrew if not present
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  fi
elif [[ "$OSTYPE" == "linux-gnu"* ]]; then            # Install dependencies for Linux
  sudo apt-get update -y && sudo apt-get install curl -y # Install curl
fi
if ! command -v uvx &> /dev/null; then                # Install uv package manager if not present
  curl -LsSf https://astral.sh/uv/install.sh | sh
  source $HOME/.local/bin/env
fi
uv tool install copier                                # Install copier as global tool
```

**Step 2**: Now create an empty repository on GitHubm, clone to your local machine, and change into it's directory.

**Step 3**: Scaffold the project
```shell
copier copy gh:helmut-hoffer-von-ankershoffen/oe-python-template .
```
**Step 4**: Setup the local environment

```shell
uv run nox -s setup_dev
```

**Step 5**: Perform initial commit and push
```shell
git add .
git commit -m "feat: Initial commit"
git push
```

Visit your GitHub repository and check the Actions tab. The CI workflow should fail at the SonarQube step,
as this external service is not yet configured for our new repository.

**Step 6**: Follow the [instructions](SERVICE_CONNECTIONS.md) to wire up
external services such as Cloudcov, SonarQube Cloud, Read The Docs, Docker.io, GHCR.io and Streamlit Community Cloud.

**Step 7**: Release the first versions
```shell
./bump
```
Notes:
* You can remove this section post having successfully scafolded your project.
* The following sections refer to the dummy application and service provided by this template.
  Use them as inspiration and adapt them to your own project.

## Overview

Adding Starbridge to your project as a dependency is easy.

```shell
uv add starbridge             # add dependency to your project
```

If you don't have uv installed follow [these instructions](https://docs.astral.sh/uv/getting-started/installation/). If you still prefer pip over the modern and fast package manager [uv](https://github.com/astral-sh/uv), you can install the library like this:

```shell
pip install starbridge        # add dependency to your project
```

Executing the command line interface (CLI) in an isolated Python environment is just as easy:

```shell
uvx starbridge hello-world     # prints "Hello, world! [..]"
uvx starbridge serve           # serves webservice API
uvx starbridge serve --port=4711 # serves webservice API on port 4711
```

Notes:
* The API is versioned, mounted at ```/api/v1``` resp. ```/api/v2```
* While serving the webservice API go to [http://127.0.0.1:8000/api/v1/hello-world](http://127.0.0.1:8000/api/v1/hello-world) to see the respons of the ```hello-world``` operation.
* Interactive documentation is provided at [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)


The CLI provides extensive help:

```shell
uvx starbridge --help                # all CLI commands
uvx starbridge hello-world --help    # help for specific command
uvx starbridge echo --help
uvx starbridge openapi --help
uvx starbridge serve --help
```


## Operational Excellence

This project is designed with operational excellence in mind, using modern Python tooling and practices. It includes:

* Various examples demonstrating usage:
  - [Simple Python script](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/examples/script.py)
  - [Streamlit web application](https://starbridge.streamlit.app/) deployed on [Streamlit Community Cloud](https://streamlit.io/cloud)
  - [Jupyter](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/examples/notebook.ipynb) and [Marimo](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/examples/notebook.py) notebook
* [Complete reference documentation](https://starbridge.readthedocs.io/en/latest/reference.html) on Read the Docs
* [Transparent test coverage](https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/starbridge) including unit and E2E tests (reported on Codecov)
* Matrix tested with [multiple python versions](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/noxfile.py) to ensure compatibility (powered by [Nox](https://nox.thea.codes/en/stable/))
* Compliant with modern linting and formatting standards (powered by [Ruff](https://github.com/astral-sh/ruff))
* Up-to-date dependencies (monitored by [Renovate](https://github.com/renovatebot/renovate) and [GitHub Dependabot](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/security/dependabot))
* [A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge) in security, maintainability, and reliability with low technical debt and codesmell (verified by SonarQube)
* Additional code security checks using [GitHub CodeQL](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/security/code-scanning)
* [Security Policy](SECURITY.md)
* [License](LICENSE) compliant with the Open Source Initiative (OSI)
* 1-liner for installation and execution of command line interface (CLI) via [uv(x)](https://github.com/astral-sh/uv) or [Docker](https://hub.docker.com/r/helmuthva/starbridge/tags)
* Setup for developing inside a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) included (supports VSCode and GitHub Codespaces)

## Example Prompts

* "Create a page about road cycling, focusing on Canyon bikes, in the personal confluence space of Helmut."

## Setup

```uvx starbridge install``` - that's all.

Prequisites:
- You are running Mac OS X
- You already have the uv package manager installed
- You already have Claude Desktop for Mac OS X installed
- You don't care for the imaging extra

If you need to first install homebrew and uv - and care for all extras:

```shell
if [[ "$OSTYPE" == "darwin"* ]]; then # Install dependencies for macOS X
  if ! command -v brew &> /dev/null; then # Install Homebrew if not present
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  fi
  brew install cairo
elif [[ "$OSTYPE" == "linux-gnu"* ]]; then # Install dependencies for Linux
  sudo apt-get update -y && sudo apt-get install curl libcairo2 -y
fi
if ! command -v uvx &> /dev/null; then # Install uv package manager if not present
  curl -LsSf https://astral.sh/uv/install.sh | sh
  source $HOME/.local/bin/env
fi
uvx --with "starbridge[imaging]" starbridge install # Install starbridge, including configuration and injection into Claude Desktop App
```

Starbridge can be [run within Docker](https://starbridge.readthedocs.io/en/latest/docker.html).

## MCP Server

Starbridge implements the [MCP Server](https://modelcontextprotocol.io/docs/concepts/architecture) interface, with Claude acting as an MCP client.

### Resources

[TODO: Document resources exposed to Claude Desktop]

### Prompts

[TODO: Document prompts exposed to Claude Desktop]

### Tools

[TODO: Document tools exposed to Claude Desktop]

## CLI

[TODO: Document CLI commands]


## Further Reading

* The [Docker manual](https://starbridge.readthedocs.io/en/latest/docker.html) explains how to run Starbridge within Docker.
* Check out the [reference](https://starbridge.readthedocs.io/en/latest/reference.html) with detailed documentation of public classes and functions.
* Our [release notes](https://starbridge.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes.
* In case you want to help us improve Starbridge: The [contribution guidelines](https://starbridge.readthedocs.io/en/latest/contributing.html) explain how to setup your development environment and create pull requests.

## Additional Resources

* [MCP Press release](https://www.anthropic.com/news/model-context-protocol)
* [MCP Specification and SDKs](https://github.com/modelcontextprotocol)
* [MCP Info to amend Claude's context](https://modelcontextprotocol.io/llms-full.txt)

## Star History

<a href="https://star-history.com/#helmut-hoffer-von-ankershoffen/starbridge">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/starbridge&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/starbridge&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/starbridge&type=Date" />
 </picture>
</a>
