Metadata-Version: 2.4
Name: timesheet-mcp-server
Version: 2.0.0
Summary: Timesheet Management System MCP Server - Based on FastMCP 2.0
Project-URL: Homepage, https://github.com/yangyuezheng/ai-emp
Project-URL: Documentation, https://github.com/yangyuezheng/ai-emp/tree/feature/mcp-server-v2-fastmcp/timesheet-mcp-server-v2
Project-URL: Repository, https://github.com/yangyuezheng/ai-emp
Project-URL: Issues, https://github.com/yangyuezheng/ai-emp/issues
Author-email: Vincent Yang <yangyuezheng@example.com>
License: MIT
License-File: LICENSE
Keywords: claude,fastmcp,mcp,model-context-protocol,timesheet
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: flake8>=7.0.0; extra == 'dev'
Requires-Dist: httpx-mock>=0.15.0; extra == 'dev'
Requires-Dist: isort>=5.13.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: types-python-dotenv>=1.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Timesheet MCP Server

[![PyPI version](https://badge.fury.io/py/timesheet-mcp-server.svg)](https://badge.fury.io/py/timesheet-mcp-server)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server for timesheet management system, built with FastMCP 2.0.

## 🚀 Quick Start

### Installation

Using uvx (recommended):
```bash
uvx timesheet-mcp-server
```

Using pip:
```bash
pip install timesheet-mcp-server
```

### Configuration

Set up your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "timesheet": {
      "command": "uvx",
      "args": ["timesheet-mcp-server"],
      "env": {
        "TIMESHEET_API_BASE_URL": "http://127.0.0.1:8080/api",
        "TIMESHEET_API_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

## ✨ Features

### Time Entry Queries (2)
- Get my time entries with filters
- Get recent time entries

### User Queries (3)
- Search users by name
- Get user details
- Get user time entries

### Project Queries (7)
- List projects with filters
- Get my projects
- Get project tree structure
- Get project members
- Get project details
- Get project time plan
- List business lines

### Reports & Statistics (5)
- Time statistics with grouping
- Time entry reports
- Project time reports
- Working days information
- Time entry warnings

## 📖 Usage Examples

After setting up, you can use natural language in Claude Desktop:

```
Please show me my time entries

List all projects

Search for user "John Doe"

Get time statistics for this week

Show me project details for project #123
```

## 🔧 Environment Variables

- `TIMESHEET_API_BASE_URL` - API base URL (required)
- `TIMESHEET_API_TOKEN` - JWT token for authentication (required)
- `MCP_TRANSPORT` - Transport method (default: stdio)
- `MCP_LOG_LEVEL` - Logging level (default: INFO)

## 🛠️ Development

Clone the repository:
```bash
git clone https://github.com/yangyuezheng/ai-emp.git
cd ai-emp/timesheet-mcp-server-v2
```

Install dependencies:
```bash
pip install -r requirements.txt
```

Run tests:
```bash
python test_tools.py
```

## 📚 Documentation

- [Full Documentation](https://github.com/yangyuezheng/ai-emp/tree/feature/mcp-server-v2-fastmcp/timesheet-mcp-server-v2)
- [Internal Distribution Guide](https://github.com/yangyuezheng/ai-emp/blob/feature/mcp-server-v2-fastmcp/timesheet-mcp-server-v2/docs/internal-distribution-guide.md)
- [Testing Guide](https://github.com/yangyuezheng/ai-emp/blob/feature/mcp-server-v2-fastmcp/timesheet-mcp-server-v2/docs/testing-guide.md)

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📞 Support

- Issues: [GitHub Issues](https://github.com/yangyuezheng/ai-emp/issues)
- Documentation: [GitHub Docs](https://github.com/yangyuezheng/ai-emp/tree/feature/mcp-server-v2-fastmcp/timesheet-mcp-server-v2/docs)

## 🙏 Acknowledgments

- [FastMCP](https://gofastmcp.com) - MCP framework
- [Model Context Protocol](https://spec.modelcontextprotocol.io) - Protocol specification
- [Claude](https://claude.ai) - AI assistant

---

**Version:** 2.0.0
**Status:** Production Ready ✅
