<div align="center">

🚀 7pace Timetracker MCP Server

• Supercharge your Azure DevOps workflow with intelligent time tracking through AI assistants

Transform your development workflow with seamless time tracking that speaks your language – literally.

🎯 Quick Start • ✨ Features • 📖 Documentation • 🤝 Contributing

</div>

---

🎯 Why 7pace MCP?

"Stop context switching. Start smart tracking."

Traditional time tracking tools interrupt your flow. Our MCP server integrates directly into Claude AI, letting you track time using natural language without leaving your coding environment.

🔥 The Problem We Solve

• ❌ Context Switching: Jumping between IDE → Browser → Time Tracker
• ❌ Manual Entry: Remembering what you worked on hours later
• ❌ Workflow Disruption: Breaking focus to log time
• ❌ Data Silos: Time tracking disconnected from your actual work

✅ Our Solution

• ✨ Natural Language: "Log 2 hours on work item 7128 for API refactoring"
• ⚡ Zero Context Switch: Track time directly in Claude AI
• 🔄 Real-time Sync: Instant Azure DevOps integration
• 📊 Smart Reports: AI-powered insights into your productivity

---

✨ Features

<table> <tr> <td width="50%">

🎯 Core Functionality

• 🕐 Smart Time Logging - Natural language time entry
• 📋 Worklog Management - View, edit, delete entries
• 📊 Intelligent Reports - Automated time analysis
• 🔍 Advanced Filtering - Date ranges, work items, users
• ⚙️ Activity Types - Automatic resolution by name or ID

</td> <td width="50%">

🚀 Developer Experience

• 🗣️ Conversational Interface - Chat with your time tracker
• ⚡ Instant Setup - One-line NPX installation
• 🔄 Real-time Sync - Live Azure DevOps integration
• 🛡️ Type Safety - Full TypeScript support
• 📱 Universal Access - Works in Cursor, VS Code, and more

</td> </tr> </table>

---

🚀 Quick Start

Option 1: Smithery (Easiest)

# Install via Smithery CLI
npx -y @smithery/cli install @turnono/sevenpace-mcp-server --client claude

Option 2: NPX (Direct)

# Add to your MCP configuration
npx -y github:turnono/7pace-mcp-server

Option 3: Clone & Build

git clone https://github.com/turnono/7pace-mcp-server.git
cd 7pace-mcp-server
npm install && npm run build

🔧 Configuration

For Cursor IDE:

{
  "mcpServers": {
    "7pace-timetracker": {
      "command": "npx",
      "args": ["-y", "github:turnono/7pace-mcp-server"],
      "env": {
        "SEVENPACE_ORGANIZATION": "your-org",
        "SEVENPACE_TOKEN": "your-token"
      }
    }
  }
}

For VS Code:

Create .vscode/mcp.json:

{
  "servers": {
    "7pace-timetracker": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:turnono/7pace-mcp-server"],
      "env": {
        "SEVENPACE_ORGANIZATION": "your-org",
        "SEVENPACE_TOKEN": "your-token"
      }
    }
  }
}

---

🎮 Usage Examples

Natural Language Time Tracking

💬 You: "Log 3 hours on work item 1234 for yesterday's database optimization work"

🤖 Claude: ✅ Time logged successfully!
Work Item: #1234
Date: 2024-01-15
Hours: 3
Description: database optimization work

Smart Reporting

💬 You: "Show me my time report for last week"

🤖 Claude: 📈 Time Report (2024-01-08 to 2024-01-14)
Total Hours: 37.5
Total Entries: 12
Top Work Items: #1234 (8hrs), #5678 (6hrs)

Intelligent Queries

💬 You: "What did I work on yesterday?"

🤖 Claude: 📝 Time Logs (3 entries)
- Work Item #1234: API Development (4 hours)
- Work Item #5678: Bug Fixes (2.5 hours)
- Work Item #9012: Code Review (1 hour)

---

📖 API Reference

<details> <summary><strong>🕐 log_time</strong> - Log time entry for a work item</summary>

Parameters:

• workItemId (number): Azure DevOps Work Item ID
• date (string): Date in YYYY-MM-DD format
• hours (number): Hours worked
• description (string): Work description
• activityType (string, optional): Activity type name or ID

Note: The server calls 7pace using date, length and billableLength (seconds) with comment. You only provide hours; conversion is handled for you.

Example:

await log_time({
  workItemId: 7128,
  date: "2024-01-15",
  hours: 2.5,
  description: "API endpoint development",
});

</details>

<details> <summary><strong>📋 get_worklogs</strong> - Retrieve time entries with filters</summary>

Parameters:

• workItemId (number, optional): Filter by work item
• startDate (string, optional): Start date filter
• endDate (string, optional): End date filter

Example:

await get_worklogs({
  startDate: "2024-01-01",
  endDate: "2024-01-31",
  workItemId: 1234,
});

</details>

<details> <summary><strong>📘 list_activity_types</strong> - List available 7pace activity types</strong></summary>

Returns a text list of activity type IDs and names from 7pace so you can pick a valid GUID if your org requires it.

await list_activity_types();
// → 00000000-0000-0000-0000-000000000001  -  Development
//   00000000-0000-0000-0000-000000000002  -  Testing

</details>

<details> <summary><strong>✏️ update_worklog</strong> - Update existing time entry</summary>

Parameters:

• worklogId (string): ID of worklog to update
• hours (number, optional): New hours
• description (string, optional): New description
• workItemId (number, optional): New work item ID

</details>

<details> <summary><strong>🗑️ delete_worklog</strong> - Delete time entry</summary>

Parameters:

• worklogId (string): ID of worklog to delete

</details>

<details> <summary><strong>📊 generate_time_report</strong> - Generate time tracking report</summary>

Parameters:

• startDate (string): Start date in YYYY-MM-DD format
• endDate (string): End date in YYYY-MM-DD format
• userId (string, optional): Filter by user

</details>

---

🔐 Setup Guide

1. Get Your 7pace API Token

1. Navigate to Azure DevOps → 7pace Timetracker
2. Go to Settings → API & Reporting
3. Click "Create New Token"
4. Copy the token for your environment configuration

2. Environment Variables

# Required
export SEVENPACE_ORGANIZATION="your-org-name"
export SEVENPACE_TOKEN="your-api-token"

# Optional
export AZURE_DEVOPS_ORG_URL="https://dev.azure.com/your-org"
export AZURE_DEVOPS_PAT="your-devops-pat"
# Increase write timeout (ms) for slow networks (default 30000)
export SEVENPACE_WRITE_TIMEOUT_MS=45000

3. Test Your Setup

# Verify connection
npm run test

# Start in development mode
npm run dev

---

🏗️ Architecture

graph TB
    A[Claude AI] --> B[MCP Protocol]
    B --> C[7pace MCP Server]
    C --> D[7pace API]
    C --> E[Azure DevOps API]
    D --> F[Time Tracking Data]
    E --> G[Work Items]

Key Components:

• MCP Server: Handles protocol communication and business logic
• 7pace Service: Manages API interactions and data transformation
• Activity Type Resolution: Smart matching of activity names to IDs
• Error Handling: Comprehensive validation and user-friendly messages

---

🚀 Advanced Usage

Custom Activity Types

// Set default activity type
export SEVENPACE_DEFAULT_ACTIVITY_TYPE_ID="12345"

// Use activity names (auto-resolved)
log_time({
  workItemId: 1234,
  activityType: "Code Review", // Automatically resolves to ID
  // ... other params
});

Bulk Operations

// Generate comprehensive reports
generate_time_report({
  startDate: "2024-01-01",
  endDate: "2024-12-31",
  userId: "specific-user-id",
});

Integration Patterns

• Sprint Planning: Generate reports for sprint retrospectives
• Client Billing: Export time data for invoicing
• Performance Analysis: Track productivity trends
• Compliance Reporting: Automated time tracking audit trails

---

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

git clone https://github.com/turnono/7pace-mcp-server.git
cd 7pace-mcp-server
npm install
npm run dev

Contributing Guidelines

• 🐛 Bug Reports: Use GitHub Issues with detailed reproduction steps
• ✨ Feature Requests: Describe your use case and proposed solution
• 🔧 Pull Requests: Include tests and update documentation
• 📝 Documentation: Help improve our guides and examples

Development Commands

npm run build    # Compile TypeScript
npm run dev      # Development mode with hot reload
npm run test     # Run test suite
npm start        # Production mode

---

📈 Roadmap

🔜 Coming Soon

• [ ] Web Dashboard: Visual time tracking interface
• [ ] Slack Integration: Time tracking via Slack commands
• [ ] Mobile Support: Companion mobile app
• [ ] Advanced Analytics: AI-powered productivity insights
• [ ] Team Management: Multi-user organization features

🎯 Long-term Vision

• [ ] Cross-platform MCP: Support for other time tracking tools
• [ ] AI Suggestions: Intelligent work categorization
• [ ] Workflow Automation: Auto-tracking based on git commits
• [ ] Enterprise Features: SSO, audit logs, compliance reporting

---

📊 Performance & Reliability

• ⚡ Fast Response Times: < 200ms average API response
• 🔄 Smart Caching: 5-minute activity type cache for performance
• 🛡️ Error Recovery: Graceful handling of API failures
• 📈 Scalable: Handles high-volume time tracking workflows
• 🔒 Secure: Token-based authentication with environment isolation

---

🌟 Community & Support

<div align="center">

Join Our Community

Have questions? Open a GitHub Discussion
Found a bug? Report it in Issues
Need help? Check our Documentation

</div>

---

📄 License

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

---

<div align="center">

Made with ❤️ by developers, for developers

⭐ Star this repo if it helped you track time more efficiently!

🚀 Get Started • 📖 Documentation • 💬 Community

</div>