| Name | control-plane-openapi-mcp JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | MCP server for Facets Control Plane OpenAPI specification |
| upload_time | 2025-10-23 10:43:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
facets
mcp
openapi
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "control-plane-openapi-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "Facets, MCP, OpenAPI, Python",
"author": null,
"author_email": "Anuj Hydrabadi <anuj.hydrabadi@facets.cloud>",
"download_url": "https://files.pythonhosted.org/packages/80/85/7caf3c832db4fb884dd339c650669ceaadc2a47d7dc4f5dffba6baa00ff9/control_plane_openapi_mcp-1.0.1.tar.gz",
"platform": null,
"description": "# Control Plane OpenAPI MCP Server\n\nThis 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.\n\n## Key Features\n\n* **Real-time OpenAPI Integration** \n Automatically fetches and processes the latest OpenAPI specification from Facets Control Plane, ensuring you always have access to current API documentation.\n\n* **Built-in Script Generation Guidance** \n 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.\n\n* **Intelligent Operation Filtering** \n Automatically excludes deprecated operations (17 filtered out of 566 total) to provide clean, relevant results and improved search performance.\n\n* **Advanced Fuzzy Search** \n Search through 549 active operations and 500+ schemas using natural language queries with intelligent matching across summaries, descriptions, tags, and operation IDs.\n\n* **Comprehensive API Coverage** \n Access complete operation details including parameters, request bodies, response schemas, and authentication requirements for all Facets Control Plane endpoints.\n\n* **Smart Caching System** \n Intelligent TTL-based caching minimizes API calls while ensuring fresh data, with configurable cache duration for optimal performance.\n\n* **Detailed Schema Exploration** \n Explore complex data structures with property listings, type information, and relationship mappings for all API schemas.\n\n## Available MCP Tools\n\n| Tool Name | Description |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| `FIRST_STEP_get_api_script_guide` | **\ud83d\ude80 Start here!** Loads comprehensive API script generation guide - call this tool first before using others. |\n| `refresh_api_catalog` | Refreshes the API catalog by fetching the latest OpenAPI specification from the control plane. |\n| `search_api_operations` | Search for operations using fuzzy matching across operation IDs, summaries, descriptions, and tags. |\n| `search_api_schemas` | Search for schemas by name and description to find relevant data structures. |\n| `load_api_operation_by_operationId` | Load detailed operation information by its unique operation ID including parameters and responses. |\n| `load_api_operation_by_path_and_method` | Load operation details by specifying the exact API path and HTTP method. |\n| `load_api_schema_by_schemaName` | Load comprehensive schema details including properties, types, and validation requirements. |\n| `call_control_plane_api` | Make authenticated GET requests to the Control Plane API using the provided path. |\n\n## Available MCP Prompts\n\n| Prompt Name | Description |\n| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `Control Plane API Script Generation` | Provides step-by-step guidance for creating production-ready scripts that interact with Control Plane APIs. |\n\n## Prerequisites\n\nThe MCP Server requires [uv](https://github.com/astral-sh/uv) for dependency management and execution.\n\n#### Install `uv` with Homebrew:\n```bash\nbrew install uv\n```\n\nFor other installation methods, see the [official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).\n\n## Integration with Claude\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"control-plane-openapi\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--directory\", \"/path/to/your/cloned/control-plane-openapi-mcp\", \"control-plane-openapi-mcp\"],\n \"env\": {\n \"CONTROL_PLANE_URL\": \"https://<customername>.console.facets.cloud\",\n \"FACETS_USERNAME\": \"<YOUR_USERNAME>\",\n \"FACETS_TOKEN\": \"<YOUR_TOKEN>\",\n \"FACETS_PROFILE\": \"default\",\n \"CACHE_TTL\": \"3600\"\n }\n }\n }\n}\n```\n\n\u26a0\ufe0f Replace `<YOUR_USERNAME>` and `<YOUR_TOKEN>` with your actual Facets credentials.\n\n### Environment Variables\n\n- `CONTROL_PLANE_URL`: Base URL of the Facets Control Plane (default: demo instance)\n- `FACETS_USERNAME`: Your Facets username for API authentication\n- `FACETS_TOKEN`: Your Facets access token for API authentication\n- `FACETS_PROFILE`: Facets profile to use from credentials file (default: \"default\")\n- `CACHE_TTL`: Cache time-to-live in seconds (default: 3600)\n\n### Authentication\n\nThe server supports two authentication methods:\n\n1. **Environment Variables**: Set `FACETS_USERNAME` and `FACETS_TOKEN`\n2. **Credentials File**: Configure `~/.facets/credentials` with profile-based credentials\n\nFor credential setup, refer to the [Facets Authentication Guide](https://readme.facets.cloud/reference/authentication-setup).\n\n## Usage Highlights\n\n- Uses `search_api_operations` and `search_api_schemas` to find relevant endpoints using natural language\n- Uses specific load operations to get detailed parameter and response information\n- Uses `call_control_plane_api` to make actual API calls and get real data from your Facets environment\n- Leverages the fuzzy search to find operations even with partial or approximate terms\n\n## API Coverage\n\nThe server provides access to the complete Facets Control Plane API including:\n\n- **Stack Management**: Create, update, delete, and manage infrastructure stacks\n- **Cluster Operations**: Deploy, monitor, and manage Kubernetes clusters \n- **Artifact Management**: Handle CI/CD artifacts and routing rules\n- **User & Access Control**: Manage users, groups, roles, and permissions\n- **Resource Management**: Handle cloud resources and configurations\n- **Monitoring & Alerts**: Access deployment logs, metrics, and monitoring data\n- **Authentication**: OAuth integrations, tokens, and account management\n\n## Example Prompts\n\nWhen using with Claude, try these example prompts:\n\n```\n\"Show me all project-related operations in the Facets API\"\n\"What are the required parameters for creating a new project?\"\n\"Find operations related to environment deployments\"\n\"Show me the project schema structure with all its properties\"\n\"Generate a TypeScript interface for the project model\"\n\"Get the current list of projects from my environment\"\n\"Show me details of a specific project named 'my-production-project'\"\n\"What environments are running in my Facets environment?\"\n\"Create an example API call to get project information\"\n\"Find all endpoints that handle artifact routing\"\n\"What authentication methods are available in the API?\"\n```\n\n## Local Development\n\n### Setting Up Development Environment\n\n1. **Clone the repository**:\n ```bash\n git clone <repository-url>\n cd control-plane-openapi-mcp\n ```\n\n2. **Create virtual environment and install dependencies**:\n ```bash\n uv sync\n ```\n\n3. **Activate the virtual environment**:\n ```bash\n source .venv/bin/activate # On macOS/Linux\n # or\n .venv\\Scripts\\activate # On Windows\n ```\n\n### Testing the MCP Server\n\n```bash\n# Start the MCP server (will wait for stdin input)\nuv run control-plane-openapi-mcp\n\n# Test with custom OpenAPI URL\nFACETS_OPENAPI_URL=\"https://your-instance.com/v3/api-docs\" uv run control-plane-openapi-mcp\n```\n\n### Development Workflow\n\n1. **Make changes** to the source code\n2. **Test locally** using the example scripts\n3. **Verify MCP integration** with Claude Desktop\n4. **Run validation** to ensure no regressions\n5. **Commit changes** with descriptive messages\n\n### Project Structure\n\n```\ncontrol_plane_openapi_mcp/\n\u251c\u2500\u2500 __init__.py # Package initialization\n\u251c\u2500\u2500 config.py # Configuration and MCP setup\n\u251c\u2500\u2500 server.py # Main MCP server entry point\n\u251c\u2500\u2500 tools.py # MCP tool implementations\n\u2514\u2500\u2500 core/ # Core functionality\n \u251c\u2500\u2500 models.py # Pydantic data models\n \u251c\u2500\u2500 spec_loader.py # OpenAPI spec fetching and processing\n \u251c\u2500\u2500 spec_processor.py # Operation and schema extraction\n \u251c\u2500\u2500 search.py # Fuzzy search engine\n \u251c\u2500\u2500 cache.py # TTL-based caching\n \u2514\u2500\u2500 service.py # Main orchestrating service\n```\n\n---\n\n## Architecture\n\n- **`SpecLoader`**: Fetches and processes OpenAPI specifications with JSON reference resolution\n- **`SpecProcessor`**: Extracts operations and schemas while filtering deprecated endpoints \n- **`SearchEngine`**: Provides fuzzy search capabilities with configurable matching thresholds\n- **`OpenAPIService`**: Main service coordinating all components with intelligent caching\n- **`SimpleCache`**: TTL-based caching for performance optimization\n- **MCP Tools**: Specialized tools exposing functionality to AI assistants\n\n## License\n\nThis project is licensed under the MIT License. You are free to use, modify, and distribute it under its terms.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Facets Control Plane OpenAPI specification",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/Facets-cloud/control-plane-openapi-mcp/issues",
"Documentation": "https://github.com/Facets-cloud/control-plane-openapi-mcp#readme",
"Homepage": "https://github.com/Facets-cloud/control-plane-openapi-mcp"
},
"split_keywords": [
"facets",
" mcp",
" openapi",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b6ecbd9d7d3668ef92489b6961b348169a2b4329ccbd05dfd33b7769f37700da",
"md5": "9c7bbf9da244f05dc835c4e97cac4016",
"sha256": "9b3e717c1de8c5e10d06d0fe9f5787181c05d560854b1eb3f8b466cd892738b8"
},
"downloads": -1,
"filename": "control_plane_openapi_mcp-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c7bbf9da244f05dc835c4e97cac4016",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 25287,
"upload_time": "2025-10-23T10:43:40",
"upload_time_iso_8601": "2025-10-23T10:43:40.966980Z",
"url": "https://files.pythonhosted.org/packages/b6/ec/bd9d7d3668ef92489b6961b348169a2b4329ccbd05dfd33b7769f37700da/control_plane_openapi_mcp-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "80857caf3c832db4fb884dd339c650669ceaadc2a47d7dc4f5dffba6baa00ff9",
"md5": "844a8bcea3299c0011f138efa2bb5c84",
"sha256": "018b28f81758aa62de6acb1a889d9de60389398e0b1bdd1fe6d0a03f4bc5fb4c"
},
"downloads": -1,
"filename": "control_plane_openapi_mcp-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "844a8bcea3299c0011f138efa2bb5c84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 26031,
"upload_time": "2025-10-23T10:43:42",
"upload_time_iso_8601": "2025-10-23T10:43:42.166804Z",
"url": "https://files.pythonhosted.org/packages/80/85/7caf3c832db4fb884dd339c650669ceaadc2a47d7dc4f5dffba6baa00ff9/control_plane_openapi_mcp-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 10:43:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Facets-cloud",
"github_project": "control-plane-openapi-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "control-plane-openapi-mcp"
}
