Metadata-Version: 2.4
Name: parking-mcp-server
Version: 0.1.0
Summary: MCP server for parking system - query user info, parking plans, and orders
Project-URL: Homepage, https://github.com/yourusername/parking-mcp-server
Project-URL: Repository, https://github.com/yourusername/parking-mcp-server
Project-URL: Issues, https://github.com/yourusername/parking-mcp-server/issues
Author-email: Parking System MCP <your-email@example.com>
License: MIT License
        
        Copyright (c) 2024 Parking System MCP
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: mcp,parking,server,sqlite
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# Parking MCP Server

A Model Context Protocol (MCP) server for parking system that provides tools to query user information, parking plans, orders, and parking space status.

## Features

- 🔍 **get_user_info** - Query user basic information, parking habits, common parking lots
- 📅 **get_user_parking_plans** - Query today's parking plans for a specific user
- 🎫 **get_user_orders** - Query parking orders (history + current) for a user
- 🅿️ **get_parking_space_status** - Query parking space occupancy status

## Installation

### Install from PyPI (Recommended)

```bash
pip install parking-mcp-server
```

The package includes a sample SQLite database with parking data, so it works out-of-the-box!

### Install from Source

```bash
git clone https://github.com/yourusername/parking-mcp-server.git
cd parking-mcp-server
pip install -e .
```

## Prerequisites

- Python 3.8+
- MCP-compatible client (Claude Desktop, Cursor, etc.)
- (Optional) Your own SQLite database if you want to use custom data

## Quick Start

### 1. Install and Run (Out-of-the-Box)

The package includes a sample SQLite database, so you can start immediately:

```bash
# Install from PyPI
pip install parking-mcp-server

# Run the server (uses included sample database)
parking-mcp-server

# The server will automatically use the packaged parking.db
```

### 2. Use Your Own Database (Optional)

If you have your own parking database, you can use it instead:

**Method A: Environment Variable**
```bash
export PARKING_DB_PATH=/path/to/your/parking.db
parking-mcp-server
```

**Method B: Command Line Argument**
```bash
parking-mcp-server --db-path /path/to/your/parking.db
```

**Method C: Place in Current Directory**
```bash
cd /path/to/your/db
cp /path/to/your/parking.db .
parking-mcp-server
```

### 3. Configure MCP Client

Once the server is running, configure your MCP client:

**Claude Desktop:**
```json
{
  "mcpServers": {
    "parking-system": {
      "command": "parking-mcp-server",
      "env": {
        "PARKING_DB_PATH": "/path/to/your/parking.db"
      }
    }
  }
}
```

**Without environment variable (uses packaged or default DB):**
```json
{
  "mcpServers": {
    "parking-system": {
      "command": "parking-mcp-server"
    }
  }
}
```

### 4. Configure MCP Client

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "parking-system": {
      "command": "parking-mcp-server",
      "env": {
        "PARKING_DB_PATH": "/path/to/your/parking.db"
      },
      "transport": "stdio"
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "parking-system": {
      "command": "parking-mcp-server",
      "env": {
        "PARKING_DB_PATH": "/path/to/your/parking.db"
      }
    }
  }
}
```

## Available Tools

### get_user_info

Query user basic information including profile, parking habits, and preferences.

**Parameters:**
- `user_id` (integer, required): The ID of the user to query

**Example in MCP client:**
```
What's the parking habit of user 10001?
```

### get_user_parking_plans

Query today's parking plans for a specific user.

**Parameters:**
- `user_id` (integer, required): The ID of the user to query

**Example in MCP client:**
```
Show me today's parking plans for user 10001
```

### get_user_orders

Query parking orders (both historical and current) for a user.

**Parameters:**
- `user_id` (integer, required): The ID of the user to query

**Example in MCP client:**
```
What are the recent parking orders for user 10001?
```

### get_parking_space_status

Query parking space occupancy status across all parking lots or a specific one.

**Parameters:**
- `park_id` (string, optional): Specific parking lot ID to query. If omitted, returns all parking lots.

**Example in MCP client:**
```
What's the current occupancy status of parking lot TCC0001?
Show me the status of all parking spaces
```

## Database Schema

The package includes a sample database with the following tables:

### Sample Data Included

- **3,000 users** with various parking habits (Pendulum, Random, Task-driven, Nail users)
- **1,000 parking spaces** across 20 parking lots
- **9,413 parking plans** for simulation
- **2,917 parking orders** (completed and active)

### Table Structure

#### t_users
- `user_id` (INTEGER, PRIMARY KEY)
- `user_name` (TEXT)
- `plate_number` (TEXT)
- `phone_number` (TEXT)
- `payment_habit` (TEXT) - Forgetting, Watching, Busy, Malicious
- `parking_habit` (TEXT) - Pendulum, Random, Task-driven, Nail user
- `working_time` (TEXT) - For pendulum users
- `offwork_time` (TEXT) - For pendulum users
- `common_park_ids` (TEXT) - Comma-separated parking lot IDs
- `common_park_label` (TEXT) - Comma-separated zone types
- `is_wechat_bound` (INTEGER) - 0 or 1
- `create_time` (TEXT)

#### t_parking_space
- `space_id` (TEXT, PRIMARY KEY) - Format: T0001
- `park_id` (TEXT) - Format: TCC0001 to TCC0020
- `zone_type` (TEXT) - Residential, Office, Commercial, Entertainment, Street, Special
- `is_used` (INTEGER) - 0 (available) or 1 (occupied)
- `used_time` (TEXT) - Timestamp of last status change
- `create_time` (TEXT)

#### t_will_parking (Parking Plans)
- `id` (INTEGER, PRIMARY KEY)
- `user_id` (INTEGER)
- `parking_in_time` (TEXT) - Predicted entry time
- `parking_out_time` (TEXT) - Predicted exit time
- `target_zones` (TEXT) - Target parking zones
- `status` (INTEGER) - 0=pending, 1=active, 2=completed, -1=cancelled
- `plan_date` (TEXT) - Date of the plan

#### t_parking_orders (Real Orders)
- `order_id` (TEXT, PRIMARY KEY) - UUID
- `user_id` (INTEGER)
- `space_id` (TEXT) - Actual occupied space
- `park_id` (TEXT) - Parking lot ID
- `start_time` (TEXT) - Actual entry time
- `end_time` (TEXT) - Actual exit time (NULL if still active)

## For Developers

If you want to generate your own data instead of using the sample database:

```bash
# Clone the data generation scripts from the repository
git clone https://github.com/yourusername/parking-mcp-server.git
cd parking-mcp-server

# Generate parking spaces
python generate_mock_spaces.py 1000

# Generate users
python generate_mock_users.py 3000

# Generate parking plans and run simulation
python simulation_engine.py
```

Then configure the MCP server to use your generated database:
```bash
export PARKING_DB_PATH=./parking.db
parking-mcp-server
```

## Development

### Setup Development Environment

```bash
git clone https://github.com/yourusername/parking-mcp-server.git
cd parking-mcp-server
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Building Distribution

```bash
# Build wheel and source distribution
python -m build

# Upload to PyPI (requires credentials)
python -m twine upload dist/*
```

## Environment Variables

- `PARKING_DB_PATH`: Path to SQLite database file (default: `parking.db`)

## Troubleshooting

### Database not found error

Make sure the database file exists and the path is correctly set:
```bash
export PARKING_DB_PATH=/absolute/path/to/parking.db
```

### MCP client not connecting

1. Check that the server starts without errors
2. Verify the command path in MCP client configuration
3. Ensure the database is accessible
4. Check logs for any error messages

### Permission errors

Ensure the database file has appropriate read permissions:
```bash
chmod 644 parking.db
```

## License

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

## Contributing

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

## Support

If you encounter any issues or have questions:
- Open an issue on GitHub: https://github.com/yourusername/parking-mcp-server/issues
- Check the documentation above
- Ensure all prerequisites are met
