mcp-acc-issues

# MCP-ACC-Issues A Python client for interacting with Autodesk Construction Cloud (ACC) Issues API through natural language using Claude AI. ## Features - Schema-driven development with Pydantic models - Natural Language Processing for issue queries and report generation - Support for multiple report formats (Markdown, JSON, CSV, HTML) - Comprehensive test coverage - Type-safe API client - OAuth2 authentication support - MCP server with API key authentication ## Installation ```bash # Using UV (recommended) uv venv .venv source .venv/bin/activate # On Unix/macOS # or .venv\Scripts\activate # On Windows uv pip install -e . # Using pip pip install -e . ``` ## Configuration Set up your Autodesk API credentials as environment variables: ```bash export AUTODESK_CLIENT_ID="your_client_id" export AUTODESK_CLIENT_SECRET="your_client_secret" ``` ## Authentication This application uses 3-legged OAuth authentication with Autodesk Construction Cloud APIs. This means that users need to authenticate through their Autodesk account to grant access to the application. ### OAuth Server The package includes an OAuth server that handles the authentication flow: ```bash # Start the OAuth server python oauth_server.py ``` This will start a server at http://127.0.0.1:8000/ where users can log in with their Autodesk account. ### Getting Access Tokens After logging in through the OAuth server, you can extract the access token: ```bash # Get the latest access token python get_token.py ``` ### Using Access Tokens You can use the access token with the provided scripts: ```bash # List projects python list_projects.py # List issues in a project python list_issues.py --token "your_access_token" ``` ## Usage ### Basic Usage ```python from mcp_acc_issues.api import IssuesClient from mcp_acc_issues.schemas import CreateIssue, IssueStatus # Client automatically uses environment variables client = IssuesClient.from_env() # Create an issue issue = client.create_issue( project_id="your_project_id", title="New Issue", description="This is a test issue", status=IssueStatus.OPEN ) # Get issue details issue = client.get_issue(project_id="your_project_id", issue_id="issue_id") # Search issues results = client.search_issues(query_params={ "project_id": "your_project_id", "status": ["open", "in_progress"] }) ``` ### Natural Language Interface ```python from mcp_acc_issues.mcp.issues import search_issues, generate_report # Search issues using natural language result = search_issues( project_id="your_project_id", query="Show me all open issues assigned to John created last week" ) # Generate a report result = generate_report( project_id="your_project_id", description="Generate a status report of all issues grouped by status", format="markdown" ) ``` ### Running the MCP Server The package includes a complete MCP server that can be accessed by Claude or other AI systems to interact with Autodesk Construction Cloud Issues. #### Generate an API Key ```bash # Generate a secure API key mcp-acc-issues generate-key ``` Add the generated key to your `.env` file: ``` AUTODESK_CLIENT_ID=your_client_id AUTODESK_CLIENT_SECRET=your_client_secret MCP_API_KEY=your_generated_api_key ``` #### Start the Server ```bash # Start the server using the API key from .env mcp-acc-issues serve # Or provide the API key directly mcp-acc-issues serve --api-key your_api_key # Run in development mode without authentication (not recommended for production) mcp-acc-issues serve --insecure ``` #### Making MCP Function Calls When the server is running, you can make MCP function calls to the `/mcp/call` endpoint: ```bash curl -X POST http://localhost:8000/mcp/call \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key" \ -d '{ "function": "search_issues", "parameters": { "project_id": "your_project_id", "query": "Show me all open issues" } }' ``` #### Claude Integration To integrate with Claude, configure the MCP endpoint in your Claude configuration: ```json { "name": "search_issues", "description": "Search for issues using natural language", "endpoint": "http://your-server:8000/mcp/call", "headers": { "X-API-Key": "your_api_key" }, "parameters": { "function": "search_issues", "parameters": { "project_id": "string", "query": "string" } } } ``` ## Development ### Setup Development Environment ```bash # Create and activate virtual environment uv venv .venv source .venv/bin/activate # On Unix/macOS # or .venv\Scripts\activate # On Windows # Install development dependencies uv pip install -e ".[dev]" ``` ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=mcp_acc_issues # Run specific test file pytest tests/test_client.py ``` ### Code Quality ```bash # Run linting ruff check . # Run type checking mypy src # Format code black . isort . ``` ## License MIT License ## Contributing 1. Fork the repository 2. Create a feature branch 3. Commit your changes 4. Push to the branch 5. Create a Pull Request