Metadata-Version: 2.4
Name: pkgq
Version: 0.1.1
Summary: Package Query - Find API information for Python packages
Project-URL: Homepage, https://github.com/christophevg/pkgq
Project-URL: Documentation, https://github.com/christophevg/pkgq#readme
Project-URL: Repository, https://github.com/christophevg/pkgq
Project-URL: Issues, https://github.com/christophevg/pkgq/issues
Author-email: Christophe VG <contact@christophe.vg>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,api,documentation,mcp,package,query
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: twine>=6.0.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# pkgq

**PacKaGe Query** - Find API information for Python packages.

A fast, agent-friendly tool for discovering Python package documentation, capabilities, and migration guides.

## Installation

```bash
# Install with uv
uv add pkgq

# Or with pip
pip install pkgq

# For MCP server support
uv add "pkgq[mcp]"
```

## Usage

### Python Module

```python
from pkgq import find

# Find package documentation
result = find("yoker")
print(result.content)

# Find specific version
result = find("yoker", version="2.1.0")

# Check for updates
result = find("yoker", from_version="1.5.0")
if result.version != "1.5.0":
    print(f"Update available: {result.version}")

# Save to cache
result.save_to_cache()
```

### Command Line

```bash
# Find package documentation
pkgq find yoker

# Find specific version
pkgq find yoker --version 2.1.0

# Check for updates
pkgq find yoker --from-version 1.5.0

# Save to cache
pkgq find yoker --save

# Output as JSON
pkgq find yoker --json

# Manage cache
pkgq cache --list
pkgq cache --clear
pkgq cache --dir
```

### MCP Server

```bash
# Run MCP server
pkgq-mcp-server

# Or with uvx
uvx --from pkgq pkgq-mcp-server
```

The MCP server provides a `find_package` tool for use with Claude Code and other MCP-compatible agents.

## Cache

Package documentation is cached locally:

- Default: `~/.cache/pkgq/packages/`
- Custom: Set `PKGQ_CACHE` environment variable

Cache structure:
```
~/.cache/pkgq/packages/
├── yoker/
│   ├── PACKAGE.md      # Package documentation
│   └── metadata.json   # Version and source info
└── roomz/
    ├── PACKAGE.md
    └── metadata.json
```

## Development

```bash
# Clone repository
git clone https://github.com/christophevg/pkgq.git
cd pkgq

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run linter
uv run ruff check src/

# Run MCP server
uv run pkgq-mcp-server
```

## License

MIT License - See [LICENSE](LICENSE) for details.