Metadata-Version: 2.4
Name: pensero-mcp-client
Version: 0.1.1
Summary: MCP client for Pensero - Query engineering metrics from Claude Desktop
Project-URL: Homepage, https://pensero.com
Project-URL: Documentation, https://help.pensero.ai/en/
Author: Pensero
License: MIT
License-File: LICENSE
Keywords: claude,engineering,mcp,metrics,pensero
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
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Pensero MCP Client

Query your engineering metrics from Claude Desktop using the Pensero MCP client.

## What is this?

This is a lightweight client that connects Claude Desktop to your Pensero account, allowing you to:

- Query pull requests, commits, and code reviews
- Analyze team productivity and delivery metrics
- Aggregate engineering data with natural language queries
- Get insights from work items, tickets, and documents

## Installation

### Quick Start (Recommended)

```bash
uvx pensero-mcp-client
```

This will download and run the latest version without installing anything permanently.

### Alternative: Install with pip

```bash
pip install pensero-mcp-client
```

## Setup

### Step 1: Get Your API Token

1. Log in to [Pensero](https://pensero.com)
2. Go to **Settings → API Tokens**
3. Click **Create New Token**
4. Give it a name (e.g., "Claude Desktop")
5. Copy the `token:secret` pair (you'll only see this once!)

### Step 2: Configure Claude Desktop

Edit your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add this configuration:

```json
{
  "mcpServers": {
    "pensero": {
      "command": "uvx",
      "args": ["pensero-mcp-client"],
      "env": {
        "PENSERO_API_TOKEN": "tk_xxxxxxxxxxxxx:sk_xxxxxxxxxxxxx"
      }
    }
  }
}
```

**Note**: Using `uvx` automatically downloads and runs the latest version - no manual installation needed!

Replace `tk_xxxxxxxxxxxxx:sk_xxxxxxxxxxxxx` with your actual token from Step 1.

### Step 3: Restart Claude Desktop

Quit and restart Claude Desktop for the configuration to take effect.

## Usage

Once configured, you can ask Claude to query your Pensero data:

### Example Queries

**List available data:**
> "What data models are available in Pensero?"

**Query pull requests:**
> "Show me all merged pull requests from last week"

**Aggregate metrics:**
> "What's the average number of lines changed per PR by each developer this month?"

**Complex queries:**
> "Find all open pull requests created by the Backend team, grouped by repository"

**Team analytics:**
> "How many tickets did each team member complete this sprint?"


## Troubleshooting

### "PENSERO_API_TOKEN environment variable not set"

Make sure you've added the token to your Claude Desktop configuration and restarted Claude Desktop.

### "Authentication failed"

- Verify your token is correct
- Check the token hasn't been revoked in Pensero settings
- Ensure the token format is `token:secret` (with colon)

### "Connection error"

- Check your internet connection
- Verify you can access https://pensero.com

### "Rate limit exceeded"

You've made too many requests. The default limit is 1,000 requests per hour per user. Wait a few minutes and try again.

### Server not starting

Check Claude Desktop logs:
- **macOS**: `~/Library/Logs/Claude/mcp*.log`
- **Windows**: `%APPDATA%\Claude\logs\mcp*.log`

## Available Models

The client provides access to these Pensero data models:

### Git
- **GitPullRequest**: Pull requests/merge requests with metadata, metrics, and state
- **GitPullRequestReview**: Code reviews on pull requests
- **GitRepository**: Git repositories tracked in Pensero
- **GitUser**: Git users (developers contributing to repositories)

### Ticketing
- **Ticket**: Work tickets from issue tracking systems (Jira, Linear, etc.)
- **TicketingUser**: Users from ticketing systems
- **TicketingRepository**: Ticketing system integrations (Jira projects, Linear workspaces, etc.)

### BOW (Bag of Work)
- **BowItem**: Unified view of work across PRs, tickets, documents, commits
- **BowChunk**: Chunks of work within BOW items
- **SuperChunk**: Aggregated chunks representing larger work units

### Documents
- **Document**: Documents from Notion, Confluence, Google Drive
- **DocumentUser**: Users from document systems
- **DocumentComment**: Comments on documents

### HR
- **OrganizationUser**: Organization users (team members)
- **Team**: Engineering teams
- **TeamMember**: Team membership records

## Security

- Your API token is stored in Claude Desktop's configuration file
- The client only makes HTTPS requests to Pensero
- Tokens can be revoked at any time from Pensero settings
- All queries respect your organization's permissions and data scoping

## Support

- **Documentation**: [help.pensero.ai](https://help.pensero.ai/en/)
- **Email**: support@pensero.com

## License

MIT License - see LICENSE file for details.
