@api-now/mcp 1.0.0

package/LICENSE.md

@@ -0,0 +1,15 @@
+# API Now Ecosystem License
+
+Copyright (c) 2025 API Now
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, merge, publish, and distribute the Software **exclusively within the API Now ecosystem**.
+
+**Restrictions:**
+
+- The Software may not be used, copied, modified, merged, published, or distributed outside of the API Now ecosystem.
+- The Software may not be sublicensed, sold, or used as part of any product or service that is not part of the API Now ecosystem.
+- Any use of the Software outside the API Now ecosystem is strictly prohibited.
+
+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.
+
+For questions about permitted use, please contact: <info@apinow.app>

package/README.md

@@ -0,0 +1,174 @@
+# API Now! Model Context Protocol (MCP) Server
+
+[![NPM Version](https://img.shields.io/npm/v/@api-now/mcp.svg)](https://www.npmjs.com/package/@api-now/mcp)
+[![License](https://img.shields.io/npm/l/@api-now/mcp.svg)](https://github.com/api-now/mcp/blob/main/LICENSE.md)
+
+An official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the **API Now!** platform. This server acts as a programmatic bridge enabling LLMs and AI agents (such as Claude Desktop, Cursor, or VS Code) to manage, design, and deploy no-code API schemas directly from their chat environment.
+
+---
+
+## Architecture Overview
+
+The API Now! platform provides an AI-first API design and management control plane using two core schemas:
+
+1. **Data Domain Models**: Representation of data entities, namespaces, structures, validation rules, and semantics.
+2. **API Models**: Expositions of the data domain to the public web (CRUD endpoints, path layouts, security rules, sessions, authorization, pagination, and rate limiting).
+
+This MCP server translates high-level agent instructions into precise modifications on these models, validating changes locally using the `@api-now/core` package before patching them back to the control plane.
+
+---
+
+## Tool Directory
+
+The server exposes tools grouped into five distinct areas.
+
+### 1. Authentication Tools (`registerAuthTools`)
+
+Manage connection profiles and session credentials with the API Now! platform.
+
+- `configure_auth`: Updates token, base API URL, and default organization. Validates credentials with the control plane before persisting.
+- `get_auth_status`: Checks connection status and displays current user info and active organization.
+
+### 2. Data Domain Tools (`registerDomainTools`)
+
+Operate on schemas defining data entities, properties, associations, namespaces, and semantics.
+
+- **Domain Management**: `create_domain`, `read_domain`, `search_domains`, `update_domain`, `delete_domain`.
+- **Structural Elements**:
+  - `add_namespace`, `update_namespace`, `remove_namespace`
+  - `add_model`, `update_model`, `remove_model`
+  - `add_entity`, `update_entity`, `remove_entity`
+  - `add_property`, `update_property`, `remove_property`
+  - `add_association`, `update_association`, `remove_association`
+- **Data Semantics & IntelliSense**:
+  - `list_intelisense_helpers`: Lists available behaviors/helper modules to enrich domain logic.
+  - `apply_intelisense_helper`: Enriches properties on an entity with semantic traits.
+- **Deletion & Removal Impact Analysis**:
+  - `analyze_domain_deletion_impact`: Evaluates data integrity impacts prior to removing components.
+  - `analyze_foreign_domain_removal_impact`: Assesses impact of removing external data domain dependencies.
+
+### 3. API Modeling Tools (`registerApiTools`)
+
+Design endpoints, expose domain entities, configure security, and manage schema migrations.
+
+- **API Management**: `create_api_model`, `read_api_model`, `search_api_models`, `update_api_model`, `delete_api_model`.
+- **Configurations**:
+  - `attach_domain_to_api`: Binds a published catalog data domain version to the API.
+  - `configure_api_session`: Sets up authentication methods (OAuth, Token, Session secret), cookies, JWTs, and global pagination.
+  - `configure_api_rules`: Declares API-wide access policies, rate limits, and metadata (licenses, contact info).
+- **Exposing Entities**:
+  - `expose_entity`: Projects a data entity into an API endpoint resource path.
+  - `update_exposed_entity`: Changes pagination settings or paths.
+  - `remove_exposed_entity`: Un-exposes an entity and its nested children from the API.
+- **Endpoint Actions**:
+  - `add_entity_action`, `update_entity_action`, `remove_entity_action`: Configures supported HTTP actions (Create, Read, Update, Delete, List, Search) with action-level security policies and pagination overrides.
+- **Safe Domain Upgrades**:
+  - `analyze_api_domain_update`: Checks compatibility of a new data domain version against exposed API endpoints and returns a `DomainUpdateReport`. It caches the report under a short-lived key to save tokens.
+  - `apply_api_domain_update`: Safely executes the schema migration using the cached `reportKey`.
+
+### 4. Catalog Tools (`registerCatalogTools`)
+
+Inspect and search domain schemas published on public or organization-level catalogs.
+
+- `list_catalogs`: Fetches accessible catalog domains.
+- `search_public_catalog`: Searches public catalog definitions.
+- `publish_catalog`: Publishes an immutable version of a domain model to the catalog.
+
+### 5. Utility Tools (`registerUtilityTools`)
+
+Shared utilities for key generation.
+
+- `generate_key`: Generates a standard Nanoid key compliant with API Now! core models. (Agents should always pre-generate keys through this tool or rely on tool responses instead of inventing random IDs).
+
+---
+
+## Installation
+
+Install the package globally or locally in your workspace:
+
+```bash
+npm install @api-now/mcp
+# or globally
+npm install -g @api-now/mcp
+```
+
+---
+
+## Configuration & Integration
+
+The server runs as a standard MCP server communicating over standard input/output (stdio).
+
+### 1. Claude Desktop Integration
+
+Add the server to your Claude Desktop configuration file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "api-now": {
+      "command": "npx",
+      "args": ["-y", "@api-now/mcp"],
+      "env": {
+        "APINOW_TOKEN": "your-personal-access-token",
+        "APINOW_ORG": "your-default-org-id"
+      }
+    }
+  }
+}
+```
+
+### 2. Cursor Integration
+
+To use this with Cursor:
+
+1. Open Cursor Settings -> **Features** -> **MCP**.
+2. Click **+ Add New MCP Server**.
+3. Fill in the details:
+   - **Name**: `API Now`
+   - **Type**: `stdio`
+   - **Command**: `npx -y @api-now/mcp`
+   - **Environment Variables**: Add `APINOW_TOKEN` and `APINOW_ORG` if preferred (the server can also be configured dynamically in-session via `configure_auth`).
+
+---
+
+## Local Development
+
+If you want to build and modify the server locally:
+
+### Prerequisites
+
+- Node.js (v18 or higher)
+- npm
+
+### Setup and Build
+
+1. Clone the repository and install dependencies:
+   ```bash
+   git clone https://github.com/api-now/mcp.git
+   cd mcp
+   npm install
+   ```
+2. Build the TypeScript source code:
+   ```bash
+   npm run build
+   ```
+3. Run the server in development mode:
+   ```bash
+   npm run dev
+   ```
+
+### Quality and Testing
+
+- **Run typechecks**: `npm run typecheck`
+- **Run tests**: `npm run test`
+- **Format code**: `npm run format`
+
+---
+
+## License
+
+Distributed under the MIT License. See [LICENSE.md](LICENSE.md) for more details.