conduit-connect

Name	conduit-connect JSON
Version	0.1.5 JSON
	download
home_page	None
Summary	Enterprise Knowledge Integration Service
upload_time	2025-02-18 23:50:46
maintainer	None
docs_url	None
author	None
requires_python	<3.13,>=3.10
license	MIT
keywords	jira confluence atlassian integration cli
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Conduit - Enterprise Knowledge Integration Service

[![PyPI version](https://badge.fury.io/py/conduit-connect.svg)](https://badge.fury.io/py/conduit-connect)

Conduit is a Python-based integration framework designed to provide a unified, consistent interface for AI tools and applications to interact with enterprise knowledge and collaboration platforms. Currently in an experimental stage and evolving rapidly, Conduit focuses on Atlassian tools (Jira and Confluence) as its initial integration targets. Our vision extends beyond just issue tracking and content management - over time,we plan to integrate with a broad ecosystem of development tools (like GitHub, Notion, Trello), knowledge bases, and productivity platforms to create a comprehensive bridge between AI assistants and your team's tools.

Conduit offers a full-featured command line interface and support for Anthropic's Model Context Protocol (MCP). While the CLI provides access to all of Conduit's capabilities, the MCP integration currently supports a focused set of core features. This allows for both comprehensive command-line usage and integration with AI tools that support MCP, such as Cursor and Claude Desktop.

## Why Conduit?

Modern software development teams rely on an ever-growing array of specialized tools throughout their development lifecycle - from issue tracking and documentation to version control and CI/CD. While each tool excels at its specific purpose, the fragmentation between these tools creates significant friction:

- Developers constantly context-switch between different tools and environments
- Information is scattered across multiple platforms, making it hard to find and connect related content
- Copy-pasting between tools is error-prone and time-consuming
- AI assistants lack unified access to your team's knowledge and workflows
- Integration efforts are often manual and don't scale well

Conduit aims to solve these challenges by:

1. **Unified Access**: Creating a single, consistent interface to interact with all your development tools
2. **AI-First Design**: Making your tools' data and functionality readily available to AI assistants
3. **Seamless Integration**: Eliminating manual copying and context switching between tools
4. **Knowledge Connection**: Linking related information across different platforms automatically
5. **Workflow Automation**: Enabling automated workflows that span multiple tools

By bridging the gaps between your development tools and making them AI-accessible, Conduit helps teams stay focused on building great software rather than juggling tools.

## Features

- **Jira Integration**

  - Multi-site support with site aliases
  - Retrieve issues by key
  - Search issues using JQL
  - Create new issues with markdown formatting
  - Update issues with formatted content
  - Add formatted comments
  - Transition issue status
  - View remote links
  - Automatic markdown to Jira format conversion
  - Sprint Management:
    - Get boards by project
    - Get sprints by board
    - Add issues to sprints

- **Content Management**

  - Get paths for storing formatted content
  - Support for standard markdown formatting
  - Automatic conversion to platform-specific formats
  - Clean separation of content and commands
  - Automatic cleanup of content files after successful operations
  - Failed content handling with dedicated storage
  - Content file support for:
    - Issue descriptions
    - Issue updates
    - Comments
    - Future platform content

- **Confluence Integration**

  - Multi-site support with site aliases
  - List pages in a space with pagination
  - Get page content with formatting options
  - View child pages and hierarchies
  - Support for content cleaning and formatting
  - Rich text processing for AI consumption

- **Configuration & Usability**

  - YAML-based configuration with multi-site support
  - Robust error handling
  - Detailed logging
  - Site alias management

- **MCP Integration** (Experimental)
  - Initial support for Anthropic's Model Context Protocol
  - Compatible with Cursor and Claude Desktop
  - Subset of features currently available via MCP
  - Ongoing development toward full feature parity

## Project Structure

```
conduit/
├── cli/                    # Command-line interface
│   └── commands/          # Platform-specific commands
├── config/                # Configuration management
├── core/                  # Core functionality
├── mcp/                   # Model Context Protocol implementation
└── platforms/             # Platform integrations
    ├── confluence/        # Confluence integration
    └── jira/              # Jira integration

tests/                     # Test suite
└── platforms/            # Platform integration tests

manual_testing/           # Manual testing resources
```

The project follows a modular architecture designed for extensibility:

- **CLI Layer**: Implements the command-line interface with platform-specific command modules
- **Configuration**: Handles YAML-based configuration with multi-site support
- **Core**: Provides shared utilities for configuration, logging, and error handling
- **MCP**: Implements the Model Context Protocol for AI tool integration
- **Platforms**: Contains platform-specific implementations with a common interface
  - Each platform is isolated in its own module
  - Platform-specific clients handle API interactions
  - Common interfaces ensure consistent behavior

## Installation

### Requirements

- Python 3.10 or higher (Python 3.12 is the latest supported version)
- pip, pipx, or uv package installer

### Using pipx (Recommended)

pipx provides isolated environments for Python applications, ensuring clean installation and easy updates.

macOS/Linux:

```bash
# Install pipx if not already installed
python -m pip install --user pipx
python -m pipx ensurepath

# Install conduit
pipx install conduit-connect
```

Windows:

```powershell
# Install pipx if not already installed
python -m pip install --user pipx
python -m pipx ensurepath

# Install conduit
pipx install conduit-connect
```

### Using uv (Alternative)

uv is a fast Python package installer and resolver.

macOS/Linux:

```bash
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install conduit
uv pip install conduit-connect
```

Windows:

```powershell
# Install uv if not already installed
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install conduit
uv pip install conduit-connect
```

### Development Installation

For contributing or development:

```bash
# Clone the repository
git clone https://github.com/yourusername/conduit.git
cd conduit

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install --upgrade pip  # Ensure latest pip
pip install -e .  # Install the package in editable mode
```

The development dependencies will be installed automatically. If you need to install them manually:

```bash
pip install pytest black isort mypy ruff
```

Note: Make sure you're in the root directory of the project where `pyproject.toml` is located when running the installation commands.

## Configuration

Initialize the configuration file:

```bash
conduit --init
```

This will create a configuration file at:

- Linux/macOS: `~/.config/conduit/config.yaml`
- Windows: `%APPDATA%\conduit\config.yaml`

Example configuration with multi-site support:

```yaml
jira:
  # Default site configuration
  default-site-alias: site1
  # Additional site configurations
  sites:
    site1:
      url: "https://dev-domain.atlassian.net"
      email: "dev@example.com"
      api_token: "dev-api-token"
    site2:
      url: "https://staging-domain.atlassian.net"
      email: "staging@example.com"
      api_token: "staging-api-token"

confluence:
  # Default site configuration
  default-site-alias: site1
  # Site configurations
  sites:
    site1:
      url: "https://dev-domain.atlassian.net"
      email: "dev@example.com"
      api_token: "dev-api-token"
    site2:
      url: "https://staging-domain.atlassian.net"
      email: "staging@example.com"
      api_token: "staging-api-token"
```

To get your Atlassian API token:

1. Log in to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Copy the token and paste it in your config file

To view your configured sites:

```bash
# List all configured sites
conduit config list

# Filter by platform
conduit config list --platform jira
conduit config list --platform confluence
```

Example output:

```text
Platform: Jira
Default Site: site1
  Site: site1
    URL: https://dev-domain.atlassian.net
    Email: dev@example.com
    API Token: ****
  Site: site2
    URL: https://staging-domain.atlassian.net
    Email: staging@example.com
    API Token: ****

Platform: Confluence
Default Site: site1
  Site: site1
    URL: https://dev-domain.atlassian.net
    Email: dev@example.com
    API Token: ****
  Site: site2
    URL: https://staging-domain.atlassian.net
    Email: staging@example.com
    API Token: ****
```

Configuration Management:

- Initialize config: `conduit --init`
- Delete config: `conduit config clean`
- List configured sites: `conduit config list [--platform jira|confluence]`
- Test connection:

```bash
# Test connection to default site
conduit connect jira

# Test connection to specific site
conduit connect confluence --site site1
```

Global Options:

- `--verbose`: Enable detailed logging for troubleshooting
- `--json`: Output results in JSON format
- `--init`: Initialize configuration file

## Content Handling

Conduit uses a file-based approach for handling formatted content (descriptions, comments, etc.) to ensure reliable formatting and proper conversion between different platforms. Instead of passing content directly as command arguments, Conduit follows a two-step process:

1. Get a path for storing content:

   ```bash
   path=$(conduit get-content-path)
   ```

   This generates a unique path in your configured content directory.

2. Write your content to the file:
   ```bash
   echo "Your formatted content" > "$path"
   ```
   The content can include markdown formatting which will be automatically converted to the appropriate format for each platform.

Benefits of this approach:

- Preserves complex formatting and multi-line content
- Avoids shell escaping issues
- Enables proper markdown conversion
- Provides automatic cleanup after successful operations
- Maintains failed content for debugging

Content files are automatically:

- Cleaned up after successful operations
- Moved to a `failed_content` directory if the operation fails
- Stored in your configured content directory (`~/.config/conduit/content` by default)

## Usage

### Command Line Interface

#### Configuration Commands

1. Initialize configuration:

```bash
conduit --init
```

2. List configured sites:

```bash
# List all configured sites
conduit config list

# List only Jira sites
conduit config list --platform jira

# List only Confluence sites
conduit config list --platform confluence
```

Example output:

```text
Platform: Jira
Default Site: site1
  Site: site1
    URL: https://dev-domain.atlassian.net
    Email: dev@example.com
    API Token: ****
  Site: site2
    URL: https://staging-domain.atlassian.net
    Email: staging@example.com
    API Token: ****

Platform: Confluence
Default Site: site1
  Site: site1
    URL: https://dev-domain.atlassian.net
    Email: dev@example.com
    API Token: ****
  Site: site2
    URL: https://staging-domain.atlassian.net
    Email: staging@example.com
    API Token: ****
```

3. Delete configuration:

```bash
conduit config clean
```

4. Test connection:

```bash
# Test connection to default site
conduit connect jira

# Test connection to specific site
conduit connect confluence --site site1
```

#### Working with Content Files

Conduit uses content files for handling formatted text (descriptions, comments, etc.). Always use this two-step process:

1. Get a path for your content:

```bash
content_path=$(conduit get-content-path)
```

2. Write your content to the file:

```bash
echo "Your formatted content" > "$content_path"
```

Note: Always use a unique variable name like `content_path` (not just `path`) to avoid shell environment conflicts.

#### Jira Commands

1. Get an issue:

```bash
conduit jira issue get PROJ-123 [--site site1]
```

2. Search issues:

```bash
conduit jira issue search "project = PROJ AND status = 'In Progress'" [--site site1]
```

3. Create an issue:

```bash
# Get a path for your content
content_path=$(conduit get-content-path)

# Write your formatted content to the file
echo "# Description\n\nDetailed description with *markdown* formatting" > "$content_path"

# Create the issue using the content file
conduit jira issue create PROJ --summary "New Issue" --content-file "$content_path" --type Task [--site site1]
```

4. Update an issue:

```bash
# Update summary only
conduit jira issue update PROJ-123 --summary "Updated Summary" [--site site1]

# Update with formatted content
content_path=$(conduit get-content-path)
echo "# Updated Description\n\nNew formatted content" > "$content_path"
conduit jira issue update PROJ-123 --content-file "$content_path" [--site site1]

# Update both summary and content
conduit jira issue update PROJ-123 --summary "Updated Summary" --content-file "$content_path" [--site site1]
```

5. Add a comment:

```bash
# Get a path for your formatted comment
content_path=$(conduit get-content-path)

# Write your formatted comment to the file
echo "# Comment Title\n\n- Point 1\n- Point 2\n\n\`\`\`python\nprint('code example')\n\`\`\`" > "$content_path"

# Add the comment using the content file
conduit jira issue comment PROJ-123 --content-file "$content_path" [--site site1]
```

6. Transition issue status:

```bash
conduit jira issue status PROJ-123 "In Progress" [--site site1]
```

7. Get remote links:

```bash
conduit jira issue remote-links PROJ-123 [--site site1]
```

8. Sprint Management:

```bash
# Get boards for a project
conduit jira get-boards --project PROJ [--site site1]

# Get sprints for a board
conduit jira get-sprints BOARD-123 [--state active|future|closed] [--site site1]

# Add issues to a sprint
conduit jira add-to-sprint SPRINT-456 --issues PROJ-123 PROJ-124 [--site site1]
```

#### Confluence Commands

1. List pages in a space (limited number):

```bash
conduit confluence pages list SPACE --limit 10 [--site site1]
```

2. List all pages in a space (with pagination):

```bash
conduit confluence pages list-all SPACE --batch-size 100 [--site site1]
```

3. View child pages of a parent page:

```bash
conduit confluence pages children PAGE-ID [--site site1]
```

4. Get space content in clean format:

```bash
conduit confluence pages content SPACE --format clean [--site site1]
```

5. Get space content in storage format:

```bash
conduit confluence pages content SPACE --format storage [--site site1]
```

6. Get a specific page by title:

```bash
conduit confluence pages get SPACE "Page Title" --format clean [--site site1]
```

### Python API

```python
from conduit.platforms.jira import JiraClient
from conduit.platforms.confluence import ConfluenceClient

# Initialize Jira client with optional site alias
jira = JiraClient(site_alias="site1")  # or JiraClient() for default site
jira.connect()

# Get an issue
issue = jira.get("PROJ-123")

# Search issues
issues = jira.search("project = PROJ AND status = 'In Progress'")

# Sprint Management
# Get boards for a project
boards = jira.get_boards(project_key="PROJ")

# Get sprints for a board
sprints = jira.get_sprints(board_id="BOARD-123", state="active")

# Add issues to a sprint
jira.add_issues_to_sprint(sprint_id="SPRINT-456", issue_keys=["PROJ-123", "PROJ-124"])

# Initialize Confluence client with optional site alias
confluence = ConfluenceClient(site_alias="site1")  # or ConfluenceClient() for default site
confluence.connect()

# Get pages from a space
pages = confluence.get_pages_by_space("SPACE", limit=10)

# Get all pages with pagination
all_pages = confluence.get_all_pages_by_space("SPACE", batch_size=100)

# Get child pages
child_pages = confluence.get_child_pages("PAGE-ID")

# Get a specific page by title
page = confluence.get_page_by_title(
    "SPACE",
    "Page Title",
    expand="version,body.storage"  # optional
)

# Get space content in raw format
content = confluence.get_space_content(
    "SPACE",
    depth="all",
    limit=500,
    expand="body.storage",
    format="storage"  # default
)

# Get space content in cleaned format (for AI/LLM)
content = confluence.get_space_content(
    "SPACE",
    depth="all",
    limit=500,
    expand="body.storage",
    format="clean"
)
```

The cleaned content format (`format="clean"`) provides:

- Preserved document structure
- Markdown-style formatting
- Cleaned HTML/XML markup
- Proper handling of:
  - Headers and sections
  - Lists and tables
  - Links and references
  - Code blocks
  - Task lists
  - Special Confluence elements

## AI Assistant Integration

Conduit is designed to enhance AI coding assistants by providing them access to your organization's knowledge base. It supports two primary integration methods:

### 1. Model Context Protocol (MCP) - Experimental

Conduit provides support for Anthropic's Model Context Protocol, allowing integration with MCP-compatible AI tools. The MCP integration offers a focused set of core features, with ongoing development to expand the available capabilities. Current MCP support includes:

#### Currently Supported MCP Features

**Configuration**

- List all configured Jira and Confluence sites

**Confluence Operations**

- Get page content by title within a space
- List all pages in a space (with pagination support)

**Jira Operations**

- Search issues using JQL syntax
- Create new issues (with summary, description, and issue type)
- Update existing issues (modify summary and description)
- Sprint management:
  - Get boards (optionally filtered by project)
  - Get sprints from boards (optionally filtered by state)
  - Add issues to sprints

#### Current MCP Limitations

- Limited to core read/write operations listed above
- Additional Confluence operations (like space content, child pages) only available via CLI
- Advanced Jira features (comments, transitions, remote links) only available via CLI
- Configuration changes must be done via CLI
- Content formatting and cleanup features limited to CLI

#### Development and Testing with MCP Inspector

For development and testing, you can run the Conduit MCP server directly and explore its endpoints using the MCP Inspector:

1. After creating a venv and installing dependencies, start the MCP server in development mode:

   ```bash
   mcp dev conduit/mcp/server.py
   ```

2. Look for the MCP Inspector URL in the output:

   ```
   MCP Inspector is up and running at http://localhost:5173
   ```

3. Open the URL in your browser and click the "Connect" button to connect to the MCP server
4. Use the Inspector interface to explore available endpoints and test MCP functionality

#### Cursor Integration

1. First install Conduit following the [installation instructions above](#installation).

2. Get the full path to the MCP server:

```bash
which mcp-server-conduit
```

This will output something like `/Users/<username>/.local/bin/mcp-server-conduit`

3. Configure Cursor:
   - Open Cursor Settings > Features > MCP Servers
   - Click "+ Add New MCP Server"
   - Configure the server:
     - Name: conduit
     - Type: stdio
     - Command: [paste the full path from step 2]

For more details about MCP configuration in Cursor, see the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol).

#### Claude Desktop Integration

1. First install Conduit following the [installation instructions above](#installation).

2. Get the full path to the MCP server:

```bash
which mcp-server-conduit
```

This will output something like `/Users/<username>/.local/bin/mcp-server-conduit`

3. Configure Claude Desktop:
   - Open Claude menu > Settings > Developer > Edit Config
   - Add Conduit to the MCP servers configuration:

```json
{
  "mcpServers": {
    "conduit": {
      "command": "/Users/<username>/.local/bin/mcp-server-conduit"
    }
  }
}
```

For more details, see the [Claude Desktop MCP documentation](https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users).

### 2. Command Line Interface

## Development

1. Install development dependencies:

```bash
pip install -e ".[dev]"
```

2. Run tests:

```bash
pytest
```

3. Format code:

```bash
black .
isort .
```

4. Run type checking:

```bash
mypy .
```

## Future Enhancements

- REST API for programmatic access
- Additional platform integrations:
  - Notion
  - Trello
  - GitHub
  - Google Docs
- Enhanced authentication & security
- Batch operations
- Additional output formats

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "conduit-connect",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<3.13,>=3.10",
    "maintainer_email": null,
    "keywords": "jira, confluence, atlassian, integration, cli",
    "author": null,
    "author_email": "Tim Kitchens <codingthefuturewithai@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/1c/9a/718ba206f313550757a71110391629da0a1bf01634be5a859c698e14d596/conduit_connect-0.1.5.tar.gz",
    "platform": null,
    "description": "# Conduit - Enterprise Knowledge Integration Service\n\n[![PyPI version](https://badge.fury.io/py/conduit-connect.svg)](https://badge.fury.io/py/conduit-connect)\n\nConduit is a Python-based integration framework designed to provide a unified, consistent interface for AI tools and applications to interact with enterprise knowledge and collaboration platforms. Currently in an experimental stage and evolving rapidly, Conduit focuses on Atlassian tools (Jira and Confluence) as its initial integration targets. Our vision extends beyond just issue tracking and content management - over time,we plan to integrate with a broad ecosystem of development tools (like GitHub, Notion, Trello), knowledge bases, and productivity platforms to create a comprehensive bridge between AI assistants and your team's tools.\n\nConduit offers a full-featured command line interface and support for Anthropic's Model Context Protocol (MCP). While the CLI provides access to all of Conduit's capabilities, the MCP integration currently supports a focused set of core features. This allows for both comprehensive command-line usage and integration with AI tools that support MCP, such as Cursor and Claude Desktop.\n\n## Why Conduit?\n\nModern software development teams rely on an ever-growing array of specialized tools throughout their development lifecycle - from issue tracking and documentation to version control and CI/CD. While each tool excels at its specific purpose, the fragmentation between these tools creates significant friction:\n\n- Developers constantly context-switch between different tools and environments\n- Information is scattered across multiple platforms, making it hard to find and connect related content\n- Copy-pasting between tools is error-prone and time-consuming\n- AI assistants lack unified access to your team's knowledge and workflows\n- Integration efforts are often manual and don't scale well\n\nConduit aims to solve these challenges by:\n\n1. **Unified Access**: Creating a single, consistent interface to interact with all your development tools\n2. **AI-First Design**: Making your tools' data and functionality readily available to AI assistants\n3. **Seamless Integration**: Eliminating manual copying and context switching between tools\n4. **Knowledge Connection**: Linking related information across different platforms automatically\n5. **Workflow Automation**: Enabling automated workflows that span multiple tools\n\nBy bridging the gaps between your development tools and making them AI-accessible, Conduit helps teams stay focused on building great software rather than juggling tools.\n\n## Features\n\n- **Jira Integration**\n\n  - Multi-site support with site aliases\n  - Retrieve issues by key\n  - Search issues using JQL\n  - Create new issues with markdown formatting\n  - Update issues with formatted content\n  - Add formatted comments\n  - Transition issue status\n  - View remote links\n  - Automatic markdown to Jira format conversion\n  - Sprint Management:\n    - Get boards by project\n    - Get sprints by board\n    - Add issues to sprints\n\n- **Content Management**\n\n  - Get paths for storing formatted content\n  - Support for standard markdown formatting\n  - Automatic conversion to platform-specific formats\n  - Clean separation of content and commands\n  - Automatic cleanup of content files after successful operations\n  - Failed content handling with dedicated storage\n  - Content file support for:\n    - Issue descriptions\n    - Issue updates\n    - Comments\n    - Future platform content\n\n- **Confluence Integration**\n\n  - Multi-site support with site aliases\n  - List pages in a space with pagination\n  - Get page content with formatting options\n  - View child pages and hierarchies\n  - Support for content cleaning and formatting\n  - Rich text processing for AI consumption\n\n- **Configuration & Usability**\n\n  - YAML-based configuration with multi-site support\n  - Robust error handling\n  - Detailed logging\n  - Site alias management\n\n- **MCP Integration** (Experimental)\n  - Initial support for Anthropic's Model Context Protocol\n  - Compatible with Cursor and Claude Desktop\n  - Subset of features currently available via MCP\n  - Ongoing development toward full feature parity\n\n## Project Structure\n\n```\nconduit/\n\u251c\u2500\u2500 cli/                    # Command-line interface\n\u2502   \u2514\u2500\u2500 commands/          # Platform-specific commands\n\u251c\u2500\u2500 config/                # Configuration management\n\u251c\u2500\u2500 core/                  # Core functionality\n\u251c\u2500\u2500 mcp/                   # Model Context Protocol implementation\n\u2514\u2500\u2500 platforms/             # Platform integrations\n    \u251c\u2500\u2500 confluence/        # Confluence integration\n    \u2514\u2500\u2500 jira/              # Jira integration\n\ntests/                     # Test suite\n\u2514\u2500\u2500 platforms/            # Platform integration tests\n\nmanual_testing/           # Manual testing resources\n```\n\nThe project follows a modular architecture designed for extensibility:\n\n- **CLI Layer**: Implements the command-line interface with platform-specific command modules\n- **Configuration**: Handles YAML-based configuration with multi-site support\n- **Core**: Provides shared utilities for configuration, logging, and error handling\n- **MCP**: Implements the Model Context Protocol for AI tool integration\n- **Platforms**: Contains platform-specific implementations with a common interface\n  - Each platform is isolated in its own module\n  - Platform-specific clients handle API interactions\n  - Common interfaces ensure consistent behavior\n\n## Installation\n\n### Requirements\n\n- Python 3.10 or higher (Python 3.12 is the latest supported version)\n- pip, pipx, or uv package installer\n\n### Using pipx (Recommended)\n\npipx provides isolated environments for Python applications, ensuring clean installation and easy updates.\n\nmacOS/Linux:\n\n```bash\n# Install pipx if not already installed\npython -m pip install --user pipx\npython -m pipx ensurepath\n\n# Install conduit\npipx install conduit-connect\n```\n\nWindows:\n\n```powershell\n# Install pipx if not already installed\npython -m pip install --user pipx\npython -m pipx ensurepath\n\n# Install conduit\npipx install conduit-connect\n```\n\n### Using uv (Alternative)\n\nuv is a fast Python package installer and resolver.\n\nmacOS/Linux:\n\n```bash\n# Install uv if not already installed\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install conduit\nuv pip install conduit-connect\n```\n\nWindows:\n\n```powershell\n# Install uv if not already installed\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Install conduit\nuv pip install conduit-connect\n```\n\n### Development Installation\n\nFor contributing or development:\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/conduit.git\ncd conduit\n\n# Create and activate virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install --upgrade pip  # Ensure latest pip\npip install -e .  # Install the package in editable mode\n```\n\nThe development dependencies will be installed automatically. If you need to install them manually:\n\n```bash\npip install pytest black isort mypy ruff\n```\n\nNote: Make sure you're in the root directory of the project where `pyproject.toml` is located when running the installation commands.\n\n## Configuration\n\nInitialize the configuration file:\n\n```bash\nconduit --init\n```\n\nThis will create a configuration file at:\n\n- Linux/macOS: `~/.config/conduit/config.yaml`\n- Windows: `%APPDATA%\\conduit\\config.yaml`\n\nExample configuration with multi-site support:\n\n```yaml\njira:\n  # Default site configuration\n  default-site-alias: site1\n  # Additional site configurations\n  sites:\n    site1:\n      url: \"https://dev-domain.atlassian.net\"\n      email: \"dev@example.com\"\n      api_token: \"dev-api-token\"\n    site2:\n      url: \"https://staging-domain.atlassian.net\"\n      email: \"staging@example.com\"\n      api_token: \"staging-api-token\"\n\nconfluence:\n  # Default site configuration\n  default-site-alias: site1\n  # Site configurations\n  sites:\n    site1:\n      url: \"https://dev-domain.atlassian.net\"\n      email: \"dev@example.com\"\n      api_token: \"dev-api-token\"\n    site2:\n      url: \"https://staging-domain.atlassian.net\"\n      email: \"staging@example.com\"\n      api_token: \"staging-api-token\"\n```\n\nTo get your Atlassian API token:\n\n1. Log in to https://id.atlassian.com/manage-profile/security/api-tokens\n2. Click \"Create API token\"\n3. Copy the token and paste it in your config file\n\nTo view your configured sites:\n\n```bash\n# List all configured sites\nconduit config list\n\n# Filter by platform\nconduit config list --platform jira\nconduit config list --platform confluence\n```\n\nExample output:\n\n```text\nPlatform: Jira\nDefault Site: site1\n  Site: site1\n    URL: https://dev-domain.atlassian.net\n    Email: dev@example.com\n    API Token: ****\n  Site: site2\n    URL: https://staging-domain.atlassian.net\n    Email: staging@example.com\n    API Token: ****\n\nPlatform: Confluence\nDefault Site: site1\n  Site: site1\n    URL: https://dev-domain.atlassian.net\n    Email: dev@example.com\n    API Token: ****\n  Site: site2\n    URL: https://staging-domain.atlassian.net\n    Email: staging@example.com\n    API Token: ****\n```\n\nConfiguration Management:\n\n- Initialize config: `conduit --init`\n- Delete config: `conduit config clean`\n- List configured sites: `conduit config list [--platform jira|confluence]`\n- Test connection:\n\n```bash\n# Test connection to default site\nconduit connect jira\n\n# Test connection to specific site\nconduit connect confluence --site site1\n```\n\nGlobal Options:\n\n- `--verbose`: Enable detailed logging for troubleshooting\n- `--json`: Output results in JSON format\n- `--init`: Initialize configuration file\n\n## Content Handling\n\nConduit uses a file-based approach for handling formatted content (descriptions, comments, etc.) to ensure reliable formatting and proper conversion between different platforms. Instead of passing content directly as command arguments, Conduit follows a two-step process:\n\n1. Get a path for storing content:\n\n   ```bash\n   path=$(conduit get-content-path)\n   ```\n\n   This generates a unique path in your configured content directory.\n\n2. Write your content to the file:\n   ```bash\n   echo \"Your formatted content\" > \"$path\"\n   ```\n   The content can include markdown formatting which will be automatically converted to the appropriate format for each platform.\n\nBenefits of this approach:\n\n- Preserves complex formatting and multi-line content\n- Avoids shell escaping issues\n- Enables proper markdown conversion\n- Provides automatic cleanup after successful operations\n- Maintains failed content for debugging\n\nContent files are automatically:\n\n- Cleaned up after successful operations\n- Moved to a `failed_content` directory if the operation fails\n- Stored in your configured content directory (`~/.config/conduit/content` by default)\n\n## Usage\n\n### Command Line Interface\n\n#### Configuration Commands\n\n1. Initialize configuration:\n\n```bash\nconduit --init\n```\n\n2. List configured sites:\n\n```bash\n# List all configured sites\nconduit config list\n\n# List only Jira sites\nconduit config list --platform jira\n\n# List only Confluence sites\nconduit config list --platform confluence\n```\n\nExample output:\n\n```text\nPlatform: Jira\nDefault Site: site1\n  Site: site1\n    URL: https://dev-domain.atlassian.net\n    Email: dev@example.com\n    API Token: ****\n  Site: site2\n    URL: https://staging-domain.atlassian.net\n    Email: staging@example.com\n    API Token: ****\n\nPlatform: Confluence\nDefault Site: site1\n  Site: site1\n    URL: https://dev-domain.atlassian.net\n    Email: dev@example.com\n    API Token: ****\n  Site: site2\n    URL: https://staging-domain.atlassian.net\n    Email: staging@example.com\n    API Token: ****\n```\n\n3. Delete configuration:\n\n```bash\nconduit config clean\n```\n\n4. Test connection:\n\n```bash\n# Test connection to default site\nconduit connect jira\n\n# Test connection to specific site\nconduit connect confluence --site site1\n```\n\n#### Working with Content Files\n\nConduit uses content files for handling formatted text (descriptions, comments, etc.). Always use this two-step process:\n\n1. Get a path for your content:\n\n```bash\ncontent_path=$(conduit get-content-path)\n```\n\n2. Write your content to the file:\n\n```bash\necho \"Your formatted content\" > \"$content_path\"\n```\n\nNote: Always use a unique variable name like `content_path` (not just `path`) to avoid shell environment conflicts.\n\n#### Jira Commands\n\n1. Get an issue:\n\n```bash\nconduit jira issue get PROJ-123 [--site site1]\n```\n\n2. Search issues:\n\n```bash\nconduit jira issue search \"project = PROJ AND status = 'In Progress'\" [--site site1]\n```\n\n3. Create an issue:\n\n```bash\n# Get a path for your content\ncontent_path=$(conduit get-content-path)\n\n# Write your formatted content to the file\necho \"# Description\\n\\nDetailed description with *markdown* formatting\" > \"$content_path\"\n\n# Create the issue using the content file\nconduit jira issue create PROJ --summary \"New Issue\" --content-file \"$content_path\" --type Task [--site site1]\n```\n\n4. Update an issue:\n\n```bash\n# Update summary only\nconduit jira issue update PROJ-123 --summary \"Updated Summary\" [--site site1]\n\n# Update with formatted content\ncontent_path=$(conduit get-content-path)\necho \"# Updated Description\\n\\nNew formatted content\" > \"$content_path\"\nconduit jira issue update PROJ-123 --content-file \"$content_path\" [--site site1]\n\n# Update both summary and content\nconduit jira issue update PROJ-123 --summary \"Updated Summary\" --content-file \"$content_path\" [--site site1]\n```\n\n5. Add a comment:\n\n```bash\n# Get a path for your formatted comment\ncontent_path=$(conduit get-content-path)\n\n# Write your formatted comment to the file\necho \"# Comment Title\\n\\n- Point 1\\n- Point 2\\n\\n\\`\\`\\`python\\nprint('code example')\\n\\`\\`\\`\" > \"$content_path\"\n\n# Add the comment using the content file\nconduit jira issue comment PROJ-123 --content-file \"$content_path\" [--site site1]\n```\n\n6. Transition issue status:\n\n```bash\nconduit jira issue status PROJ-123 \"In Progress\" [--site site1]\n```\n\n7. Get remote links:\n\n```bash\nconduit jira issue remote-links PROJ-123 [--site site1]\n```\n\n8. Sprint Management:\n\n```bash\n# Get boards for a project\nconduit jira get-boards --project PROJ [--site site1]\n\n# Get sprints for a board\nconduit jira get-sprints BOARD-123 [--state active|future|closed] [--site site1]\n\n# Add issues to a sprint\nconduit jira add-to-sprint SPRINT-456 --issues PROJ-123 PROJ-124 [--site site1]\n```\n\n#### Confluence Commands\n\n1. List pages in a space (limited number):\n\n```bash\nconduit confluence pages list SPACE --limit 10 [--site site1]\n```\n\n2. List all pages in a space (with pagination):\n\n```bash\nconduit confluence pages list-all SPACE --batch-size 100 [--site site1]\n```\n\n3. View child pages of a parent page:\n\n```bash\nconduit confluence pages children PAGE-ID [--site site1]\n```\n\n4. Get space content in clean format:\n\n```bash\nconduit confluence pages content SPACE --format clean [--site site1]\n```\n\n5. Get space content in storage format:\n\n```bash\nconduit confluence pages content SPACE --format storage [--site site1]\n```\n\n6. Get a specific page by title:\n\n```bash\nconduit confluence pages get SPACE \"Page Title\" --format clean [--site site1]\n```\n\n### Python API\n\n```python\nfrom conduit.platforms.jira import JiraClient\nfrom conduit.platforms.confluence import ConfluenceClient\n\n# Initialize Jira client with optional site alias\njira = JiraClient(site_alias=\"site1\")  # or JiraClient() for default site\njira.connect()\n\n# Get an issue\nissue = jira.get(\"PROJ-123\")\n\n# Search issues\nissues = jira.search(\"project = PROJ AND status = 'In Progress'\")\n\n# Sprint Management\n# Get boards for a project\nboards = jira.get_boards(project_key=\"PROJ\")\n\n# Get sprints for a board\nsprints = jira.get_sprints(board_id=\"BOARD-123\", state=\"active\")\n\n# Add issues to a sprint\njira.add_issues_to_sprint(sprint_id=\"SPRINT-456\", issue_keys=[\"PROJ-123\", \"PROJ-124\"])\n\n# Initialize Confluence client with optional site alias\nconfluence = ConfluenceClient(site_alias=\"site1\")  # or ConfluenceClient() for default site\nconfluence.connect()\n\n# Get pages from a space\npages = confluence.get_pages_by_space(\"SPACE\", limit=10)\n\n# Get all pages with pagination\nall_pages = confluence.get_all_pages_by_space(\"SPACE\", batch_size=100)\n\n# Get child pages\nchild_pages = confluence.get_child_pages(\"PAGE-ID\")\n\n# Get a specific page by title\npage = confluence.get_page_by_title(\n    \"SPACE\",\n    \"Page Title\",\n    expand=\"version,body.storage\"  # optional\n)\n\n# Get space content in raw format\ncontent = confluence.get_space_content(\n    \"SPACE\",\n    depth=\"all\",\n    limit=500,\n    expand=\"body.storage\",\n    format=\"storage\"  # default\n)\n\n# Get space content in cleaned format (for AI/LLM)\ncontent = confluence.get_space_content(\n    \"SPACE\",\n    depth=\"all\",\n    limit=500,\n    expand=\"body.storage\",\n    format=\"clean\"\n)\n```\n\nThe cleaned content format (`format=\"clean\"`) provides:\n\n- Preserved document structure\n- Markdown-style formatting\n- Cleaned HTML/XML markup\n- Proper handling of:\n  - Headers and sections\n  - Lists and tables\n  - Links and references\n  - Code blocks\n  - Task lists\n  - Special Confluence elements\n\n## AI Assistant Integration\n\nConduit is designed to enhance AI coding assistants by providing them access to your organization's knowledge base. It supports two primary integration methods:\n\n### 1. Model Context Protocol (MCP) - Experimental\n\nConduit provides support for Anthropic's Model Context Protocol, allowing integration with MCP-compatible AI tools. The MCP integration offers a focused set of core features, with ongoing development to expand the available capabilities. Current MCP support includes:\n\n#### Currently Supported MCP Features\n\n**Configuration**\n\n- List all configured Jira and Confluence sites\n\n**Confluence Operations**\n\n- Get page content by title within a space\n- List all pages in a space (with pagination support)\n\n**Jira Operations**\n\n- Search issues using JQL syntax\n- Create new issues (with summary, description, and issue type)\n- Update existing issues (modify summary and description)\n- Sprint management:\n  - Get boards (optionally filtered by project)\n  - Get sprints from boards (optionally filtered by state)\n  - Add issues to sprints\n\n#### Current MCP Limitations\n\n- Limited to core read/write operations listed above\n- Additional Confluence operations (like space content, child pages) only available via CLI\n- Advanced Jira features (comments, transitions, remote links) only available via CLI\n- Configuration changes must be done via CLI\n- Content formatting and cleanup features limited to CLI\n\n#### Development and Testing with MCP Inspector\n\nFor development and testing, you can run the Conduit MCP server directly and explore its endpoints using the MCP Inspector:\n\n1. After creating a venv and installing dependencies, start the MCP server in development mode:\n\n   ```bash\n   mcp dev conduit/mcp/server.py\n   ```\n\n2. Look for the MCP Inspector URL in the output:\n\n   ```\n   MCP Inspector is up and running at http://localhost:5173\n   ```\n\n3. Open the URL in your browser and click the \"Connect\" button to connect to the MCP server\n4. Use the Inspector interface to explore available endpoints and test MCP functionality\n\n#### Cursor Integration\n\n1. First install Conduit following the [installation instructions above](#installation).\n\n2. Get the full path to the MCP server:\n\n```bash\nwhich mcp-server-conduit\n```\n\nThis will output something like `/Users/<username>/.local/bin/mcp-server-conduit`\n\n3. Configure Cursor:\n   - Open Cursor Settings > Features > MCP Servers\n   - Click \"+ Add New MCP Server\"\n   - Configure the server:\n     - Name: conduit\n     - Type: stdio\n     - Command: [paste the full path from step 2]\n\nFor more details about MCP configuration in Cursor, see the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol).\n\n#### Claude Desktop Integration\n\n1. First install Conduit following the [installation instructions above](#installation).\n\n2. Get the full path to the MCP server:\n\n```bash\nwhich mcp-server-conduit\n```\n\nThis will output something like `/Users/<username>/.local/bin/mcp-server-conduit`\n\n3. Configure Claude Desktop:\n   - Open Claude menu > Settings > Developer > Edit Config\n   - Add Conduit to the MCP servers configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"conduit\": {\n      \"command\": \"/Users/<username>/.local/bin/mcp-server-conduit\"\n    }\n  }\n}\n```\n\nFor more details, see the [Claude Desktop MCP documentation](https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users).\n\n### 2. Command Line Interface\n\n## Development\n\n1. Install development dependencies:\n\n```bash\npip install -e \".[dev]\"\n```\n\n2. Run tests:\n\n```bash\npytest\n```\n\n3. Format code:\n\n```bash\nblack .\nisort .\n```\n\n4. Run type checking:\n\n```bash\nmypy .\n```\n\n## Future Enhancements\n\n- REST API for programmatic access\n- Additional platform integrations:\n  - Notion\n  - Trello\n  - GitHub\n  - Google Docs\n- Enhanced authentication & security\n- Batch operations\n- Additional output formats\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Enterprise Knowledge Integration Service",
    "version": "0.1.5",
    "project_urls": null,
    "split_keywords": [
        "jira",
        " confluence",
        " atlassian",
        " integration",
        " cli"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "46eeac785e229510402334db85b4038ac151a8e9c0043308373b3973fd558095",
                "md5": "e9c0671c62ef32a31a52220acab609c9",
                "sha256": "06a67cae7d95e35013eda490d3234e08c7a0d6309897a0ea02872f3b0357727e"
            },
            "downloads": -1,
            "filename": "conduit_connect-0.1.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e9c0671c62ef32a31a52220acab609c9",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.13,>=3.10",
            "size": 34605,
            "upload_time": "2025-02-18T23:50:44",
            "upload_time_iso_8601": "2025-02-18T23:50:44.685492Z",
            "url": "https://files.pythonhosted.org/packages/46/ee/ac785e229510402334db85b4038ac151a8e9c0043308373b3973fd558095/conduit_connect-0.1.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "1c9a718ba206f313550757a71110391629da0a1bf01634be5a859c698e14d596",
                "md5": "d645618f69731ecbfe54472276d4ee93",
                "sha256": "9118ecf0ad1cf8fcf9b468fab4466c9da1a26651212652633fdc1517fd04db82"
            },
            "downloads": -1,
            "filename": "conduit_connect-0.1.5.tar.gz",
            "has_sig": false,
            "md5_digest": "d645618f69731ecbfe54472276d4ee93",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.13,>=3.10",
            "size": 34978,
            "upload_time": "2025-02-18T23:50:46",
            "upload_time_iso_8601": "2025-02-18T23:50:46.601476Z",
            "url": "https://files.pythonhosted.org/packages/1c/9a/718ba206f313550757a71110391629da0a1bf01634be5a859c698e14d596/conduit_connect-0.1.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-18 23:50:46",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "conduit-connect"
}