control-plane-openapi-mcp 1.0.1__tar.gz

control_plane_openapi_mcp-1.0.1/.github/workflows/ci.yaml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+    - 'v*'
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Verify package
+      run: twine check dist/*
+
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: python -m twine upload dist/*

control_plane_openapi_mcp-1.0.1/.gitignore

@@ -0,0 +1,150 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# UV
+uv.lock
+
+# Claude Desktop logs (if any)
+claude_desktop_logs/
+
+# Development test outputs
+test_output.json
+*.tmp
+
+.claude/
+
+# Setuptools SCM version file
+*/_version.py

control_plane_openapi_mcp-1.0.1/CLAUDE.md

@@ -0,0 +1,122 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development Setup
+```bash
+# Install dependencies and setup environment
+uv sync
+source .venv/bin/activate
+
+# Run the MCP server
+uv run control-plane-openapi-mcp
+
+# Test all functionality with comprehensive example
+uv run python example.py
+
+# Run validation tests
+uv run python test_final.py
+
+# Quick function testing
+uv run python -c "from control_plane_openapi_mcp.tools import search_api_operations; print(search_api_operations('stack'))"
+```
+
+### Common Development Tasks
+```bash
+# Run individual tool tests
+uv run python dev_test.py
+
+# Test server initialization
+uv run python -m control_plane_openapi_mcp.server
+
+# Claude Desktop integration testing
+npx @modelcontextprotocol/inspector uv run --directory . control-plane-openapi-mcp
+```
+
+## Architecture Overview
+
+This is an MCP (Model Context Protocol) server that provides tools for exploring and interacting with the Facets Control Plane OpenAPI specification. The architecture follows a service-oriented design with clear separation of concerns.
+
+### Core Service Architecture
+The system is built around `OpenAPIService` (core/service.py:13) which orchestrates all operations:
+- **Lazy Loading**: Specs are fetched and cached only when first accessed
+- **Smart Caching**: TTL-based caching with configurable duration (default 1 hour)
+- **Error Boundaries**: All operations have comprehensive error handling with graceful degradation
+
+### Key Components
+1. **Spec Loading Pipeline**: 
+   - `SpecLoader` (core/spec_loader.py:14) fetches OpenAPI specs from URLs
+   - `SpecProcessor` (core/spec_processor.py:17) extracts and filters operations (excludes deprecated)
+   - JSON references are resolved using `jsonref` for proper schema handling
+
+2. **Search Engine**:
+   - `SearchEngine` (core/search.py:14) uses fuzzy matching with `fuzzywuzzy`
+   - Configurable thresholds for operation (70) and schema (80) matching
+   - Searches across names, descriptions, and tags
+
+3. **Authentication**:
+   - Supports environment variables or credentials file (~/.facets/credentials)
+   - HTTP Basic Auth for all API calls
+   - Configuration managed through `Config` (config.py:10)
+
+### MCP Integration
+The server exposes 7 tools through FastMCP:
+- API exploration tools (search, load operations/schemas)
+- API interaction tool (`call_control_plane_api` for GET requests only)
+- Catalog refresh capability
+
+## Important Implementation Details
+
+### Authentication Setup
+The system uses a two-tier authentication approach:
+1. Environment variables: `FACETS_USERNAME` and `FACETS_TOKEN`
+2. Credentials file with profile support (default profile: "default")
+
+### API Coverage
+The OpenAPI spec includes 566 total operations (549 active after filtering deprecated):
+- Stack and project management
+- Kubernetes cluster operations
+- CI/CD artifact management
+- User access control
+- Resource and configuration management
+- Monitoring and alerting
+
+### Error Handling Patterns
+All tools follow consistent error handling:
+```python
+try:
+    # Operation logic
+except Exception as e:
+    logger.error(f"Error description: {e}")
+    return {"error": str(e)}
+```
+
+### Caching Strategy
+- In-memory caching with configurable TTL
+- Separate caches for raw and processed specs
+- Manual refresh capability through `refresh_api_catalog` tool
+
+## Development Guidelines
+
+### Adding New Tools
+1. Define tool in `tools.py` using `@mcp_server.tool()` decorator
+2. Implement logic using `OpenAPIService` methods
+3. Follow existing error handling patterns
+4. Add comprehensive logging
+
+### Testing New Features
+1. Add test cases to `example.py` for comprehensive testing
+2. Use `dev_test.py` for quick iterations
+3. Validate with Claude Desktop using MCP inspector
+
+### Working with OpenAPI Specs
+- The spec includes extensive use of $ref pointers - use `jsonref` for resolution
+- Deprecated operations are automatically filtered during processing
+- Schema definitions include nested references that must be resolved
+
+### Performance Considerations
+- Large spec (>10MB) - use caching to avoid repeated fetches
+- Fuzzy search can be expensive - consider threshold tuning
+- API calls should respect rate limits of the Control Plane instance

control_plane_openapi_mcp-1.0.1/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: control-plane-openapi-mcp
+Version: 1.0.1
+Summary: MCP server for Facets Control Plane OpenAPI specification
+Author-email: Anuj Hydrabadi <anuj.hydrabadi@facets.cloud>
+License: MIT
+Project-URL: Homepage, https://github.com/Facets-cloud/control-plane-openapi-mcp
+Project-URL: Bug Tracker, https://github.com/Facets-cloud/control-plane-openapi-mcp/issues
+Project-URL: Documentation, https://github.com/Facets-cloud/control-plane-openapi-mcp#readme
+Keywords: Facets,MCP,OpenAPI,Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp[cli]
+Requires-Dist: requests>=2.31.0
+Requires-Dist: jsonref>=1.1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: fuzzywuzzy>=0.18.0
+Requires-Dist: python-levenshtein>=0.21.0
+
+# Control Plane OpenAPI MCP Server
+
+This MCP (Model Context Protocol) Server provides seamless integration with the Facets Control Plane API through its OpenAPI specification. It enables AI assistants to understand, explore, and interact with the complete Facets Control Plane API, making infrastructure management and API integration more accessible through natural language interactions.
+
+## Key Features
+
+* **Real-time OpenAPI Integration**  
+  Automatically fetches and processes the latest OpenAPI specification from Facets Control Plane, ensuring you always have access to current API documentation.
+
+* **Built-in Script Generation Guidance**  
+  Includes an MCP prompt that provides step-by-step guidance for creating production-ready scripts that interact with Control Plane APIs, with best practices for authentication, testing, and error handling.
+
+* **Intelligent Operation Filtering**  
+  Automatically excludes deprecated operations (17 filtered out of 566 total) to provide clean, relevant results and improved search performance.
+
+* **Advanced Fuzzy Search**  
+  Search through 549 active operations and 500+ schemas using natural language queries with intelligent matching across summaries, descriptions, tags, and operation IDs.
+
+* **Comprehensive API Coverage**  
+  Access complete operation details including parameters, request bodies, response schemas, and authentication requirements for all Facets Control Plane endpoints.
+
+* **Smart Caching System**  
+  Intelligent TTL-based caching minimizes API calls while ensuring fresh data, with configurable cache duration for optimal performance.
+
+* **Detailed Schema Exploration**  
+  Explore complex data structures with property listings, type information, and relationship mappings for all API schemas.
+
+## Available MCP Tools
+
+| Tool Name                               | Description                                                                                                       |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `FIRST_STEP_get_api_script_guide`       | **🚀 Start here!** Loads comprehensive API script generation guide - call this tool first before using others.  |
+| `refresh_api_catalog`                   | Refreshes the API catalog by fetching the latest OpenAPI specification from the control plane.                   |
+| `search_api_operations`                 | Search for operations using fuzzy matching across operation IDs, summaries, descriptions, and tags.             |
+| `search_api_schemas`                    | Search for schemas by name and description to find relevant data structures.                                     |
+| `load_api_operation_by_operationId`     | Load detailed operation information by its unique operation ID including parameters and responses.               |
+| `load_api_operation_by_path_and_method` | Load operation details by specifying the exact API path and HTTP method.                                        |
+| `load_api_schema_by_schemaName`         | Load comprehensive schema details including properties, types, and validation requirements.                      |
+| `call_control_plane_api`                | Make authenticated GET requests to the Control Plane API using the provided path.                               |
+
+## Available MCP Prompts
+
+| Prompt Name                               | Description                                                                                                     |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `Control Plane API Script Generation`    | Provides step-by-step guidance for creating production-ready scripts that interact with Control Plane APIs.   |
+
+## Prerequisites
+
+The MCP Server requires [uv](https://github.com/astral-sh/uv) for dependency management and execution.
+
+#### Install `uv` with Homebrew:
+```bash
+brew install uv
+```
+
+For other installation methods, see the [official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+## Integration with Claude
+
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "control-plane-openapi": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/your/cloned/control-plane-openapi-mcp", "control-plane-openapi-mcp"],
+      "env": {
+        "CONTROL_PLANE_URL": "https://<customername>.console.facets.cloud",
+        "FACETS_USERNAME": "<YOUR_USERNAME>",
+        "FACETS_TOKEN": "<YOUR_TOKEN>",
+        "FACETS_PROFILE": "default",
+        "CACHE_TTL": "3600"
+      }
+    }
+  }
+}
+```
+
+⚠️ Replace `<YOUR_USERNAME>` and `<YOUR_TOKEN>` with your actual Facets credentials.
+
+### Environment Variables
+
+- `CONTROL_PLANE_URL`: Base URL of the Facets Control Plane (default: demo instance)
+- `FACETS_USERNAME`: Your Facets username for API authentication
+- `FACETS_TOKEN`: Your Facets access token for API authentication
+- `FACETS_PROFILE`: Facets profile to use from credentials file (default: "default")
+- `CACHE_TTL`: Cache time-to-live in seconds (default: 3600)
+
+### Authentication
+
+The server supports two authentication methods:
+
+1. **Environment Variables**: Set `FACETS_USERNAME` and `FACETS_TOKEN`
+2. **Credentials File**: Configure `~/.facets/credentials` with profile-based credentials
+
+For credential setup, refer to the [Facets Authentication Guide](https://readme.facets.cloud/reference/authentication-setup).
+
+## Usage Highlights
+
+- Uses `search_api_operations` and `search_api_schemas` to find relevant endpoints using natural language
+- Uses specific load operations to get detailed parameter and response information
+- Uses `call_control_plane_api` to make actual API calls and get real data from your Facets environment
+- Leverages the fuzzy search to find operations even with partial or approximate terms
+
+## API Coverage
+
+The server provides access to the complete Facets Control Plane API including:
+
+- **Stack Management**: Create, update, delete, and manage infrastructure stacks
+- **Cluster Operations**: Deploy, monitor, and manage Kubernetes clusters  
+- **Artifact Management**: Handle CI/CD artifacts and routing rules
+- **User & Access Control**: Manage users, groups, roles, and permissions
+- **Resource Management**: Handle cloud resources and configurations
+- **Monitoring & Alerts**: Access deployment logs, metrics, and monitoring data
+- **Authentication**: OAuth integrations, tokens, and account management
+
+## Example Prompts
+
+When using with Claude, try these example prompts:
+
+```
+"Show me all project-related operations in the Facets API"
+"What are the required parameters for creating a new project?"
+"Find operations related to environment deployments"
+"Show me the project schema structure with all its properties"
+"Generate a TypeScript interface for the project model"
+"Get the current list of projects from my environment"
+"Show me details of a specific project named 'my-production-project'"
+"What environments are running in my Facets environment?"
+"Create an example API call to get project information"
+"Find all endpoints that handle artifact routing"
+"What authentication methods are available in the API?"
+```
+
+## Local Development
+
+### Setting Up Development Environment
+
+1. **Clone the repository**:
+   ```bash
+   git clone <repository-url>
+   cd control-plane-openapi-mcp
+   ```
+
+2. **Create virtual environment and install dependencies**:
+   ```bash
+   uv sync
+   ```
+
+3. **Activate the virtual environment**:
+   ```bash
+   source .venv/bin/activate  # On macOS/Linux
+   # or
+   .venv\Scripts\activate     # On Windows
+   ```
+
+### Testing the MCP Server
+
+```bash
+# Start the MCP server (will wait for stdin input)
+uv run control-plane-openapi-mcp
+
+# Test with custom OpenAPI URL
+FACETS_OPENAPI_URL="https://your-instance.com/v3/api-docs" uv run control-plane-openapi-mcp
+```
+
+### Development Workflow
+
+1. **Make changes** to the source code
+2. **Test locally** using the example scripts
+3. **Verify MCP integration** with Claude Desktop
+4. **Run validation** to ensure no regressions
+5. **Commit changes** with descriptive messages
+
+### Project Structure
+
+```
+control_plane_openapi_mcp/
+├── __init__.py              # Package initialization
+├── config.py                # Configuration and MCP setup
+├── server.py                # Main MCP server entry point
+├── tools.py                 # MCP tool implementations
+└── core/                    # Core functionality
+    ├── models.py            # Pydantic data models
+    ├── spec_loader.py       # OpenAPI spec fetching and processing
+    ├── spec_processor.py    # Operation and schema extraction
+    ├── search.py            # Fuzzy search engine
+    ├── cache.py             # TTL-based caching
+    └── service.py           # Main orchestrating service
+```
+
+---
+
+## Architecture
+
+- **`SpecLoader`**: Fetches and processes OpenAPI specifications with JSON reference resolution
+- **`SpecProcessor`**: Extracts operations and schemas while filtering deprecated endpoints  
+- **`SearchEngine`**: Provides fuzzy search capabilities with configurable matching thresholds
+- **`OpenAPIService`**: Main service coordinating all components with intelligent caching
+- **`SimpleCache`**: TTL-based caching for performance optimization
+- **MCP Tools**: Specialized tools exposing functionality to AI assistants
+
+## License
+
+This project is licensed under the MIT License. You are free to use, modify, and distribute it under its terms.