@configcat/mcp-server 0.1.2

package/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to the ConfigCat MCP Server
+
+ConfigCat MCP Server is an open source project. Feedback and contribution are welcome. Contributions are made to this repo via Issues and Pull Requests.
+
+## Submitting bug reports and feature requests
+
+The ConfigCat team monitors the [issue tracker](https://github.com/configcat/mcp-server/issues) in the ConfigCat MCP Server repository. Bug reports and feature requests specific to this MCP Server should be filed in this issue tracker. The team will respond to all newly filed issues.
+
+## Submitting pull requests
+
+We encourage pull requests and other contributions from the community. 
+- Before submitting pull requests, ensure that all temporary or unintended code is removed.
+- Be accompanied by a complete Pull Request template (loaded automatically when a PR is created).
+- Add unit or integration tests for fixed or changed functionality.
+
+When you submit a pull request or otherwise seek to include your change in the repository, you waive all your intellectual property rights, including your copyright and patent claims for the submission. For more details please read the [contribution agreement](https://github.com/configcat/legal/blob/main/contribution-agreement.md).
+
+In general, we follow the ["fork-and-pull" Git workflow](https://github.com/susam/gitpr)
+
+1. Fork the repository to your own Github account
+2. Clone the project to your machine
+3. Create a branch locally with a succinct but descriptive name
+4. Commit changes to the branch
+5. Following any formatting and testing guidelines specific to this repo
+6. Push changes to your fork
+7. Open a PR in our repository and follow the PR template so that we can efficiently review the changes.
+
+## Build instructions
+
+The project uses [npm](https://www.npmjs.com) for dependency management.
+
+### Install dependencies:
+
+```bash
+npm install
+```
+
+### Build the MCP server
+
+```bash
+npm run build
+```
+
+This will output the compiled JavaScript files to the `build/` directory (or as configured in `tsconfig.json`).
+
+### Add the MCP server to your AI tool
+
+When configuring your MCP client (e.g., Cursor, VS Code, Claude Desktop), use the absolute path to your local build. Example JSON config:
+
+```json
+{
+  "mcpServers": {
+    "ConfigCat": {
+      "command": "node",
+      "args": ["/absolute/path/to/configcat-mcp-server/build/index.js"],
+      "env": {
+        "CONFIGCAT_API_USER": "YOUR_API_USER",
+        "CONFIGCAT_API_PASS": "YOUR_API_PASSWORD",
+        "CONFIGCAT_BASE_URL": "YOUR_BASE_URL"
+      }
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/configcat-mcp-server/build/index.js` with the actual path on your machine.
+
+
+## MCP Inspector
+
+For a better development and debugging experience, try the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to test tools and more.
+
+```bash
+npx @modelcontextprotocol/inspector -e CONFIGCAT_API_USER=<user> -e CONFIGCAT_API_PASS=<password> -e CONFIGCAT_BASE_URL=https://api.configcat.com node build/index.js
+```

package/DEPLOY.md

@@ -0,0 +1,19 @@
+# Steps to deploy
+## Preparation
+1. Increase the `serverVersion` in [src/index.ts](src/index.ts).
+2. Commit & Push
+## Publish
+Use the **same version** for the git tag as in [src/index.ts](src/index.ts).
+- Via git tag
+    1. Create a new version tag.
+       ```bash
+       git tag v[MAJOR].[MINOR].[PATCH]
+       ```
+       > Example: `git tag v2.5.5`
+    2. Push the tag.
+       ```bash
+       git push origin --tags
+       ```
+- Via Github release 
+
+  Create a new [Github release](https://github.com/configcat/mcp-server/releases) with a new version tag and release notes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ConfigCat
+
+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.

package/README.md

@@ -0,0 +1,230 @@
+# ConfigCat MCP Server
+
+The ConfigCat's Model Context Protocol (MCP) server provides access to [ConfigCat's public management API](https://configcat.com/docs/api/reference/configcat-public-management-api/) for feature flag and configuration management.
+
+## Features
+
+- **Tools**: Complete set of tools for ConfigCat's public management API operations. You can Create, Read, Update and Delete any entities like Feature Flags, Configs, Environments or Products within ConfigCat.
+
+## Setup
+
+You can use the following environment variables to configure the MCP server.
+
+| Environment variable | Required | Default | Description |
+| -------------------- | -------- | ------- | ----------- |
+| CONFIGCAT_API_USER   | ☑  |         | [ConfigCat Management API basic authentication username](https://app.configcat.com/my-account/public-api-credentials). |
+| CONFIGCAT_API_PASS   | ☑  |         | [ConfigCat Management API basic authentication password](https://app.configcat.com/my-account/public-api-credentials). |
+| CONFIGCAT_BASE_URL   |          | https://api.configcat.com | ConfigCat Management API host. |
+
+
+The instructions below shows how to connect a client to the MCP server. 
+
+### Cursor
+
+1. Open `Preferences` -> `Cursor Settings` -> `MCP & Integrations`
+2. Click `Add Custom MCP`
+3. Add the following server definition for the ConfigCat MCP server:
+
+```json
+{
+  "mcpServers": {
+    "ConfigCat": {
+      "command": "npx",
+      "args": ["-y", "@configcat/mcp-server"],
+      "env": {
+        "CONFIGCAT_API_USER": "YOUR_API_USER",
+        "CONFIGCAT_API_PASS": "YOUR_API_PASSWORD"
+      }
+    }
+  }
+}
+```
+
+4. Save the settings.
+
+### Visual Studio Code
+
+1. Create a `.vscode/mcp.json` file in your project root with the following content:
+
+```json
+{
+  "servers": {
+    "ConfigCat": {
+      "command": "npx",
+      "args": ["-y", "@configcat/mcp-server"],
+      "env": {
+        "CONFIGCAT_API_USER": "YOUR_API_USER",
+        "CONFIGCAT_API_PASS": "YOUR_API_PASSWORD"
+      }
+    }
+  }
+}
+```
+
+2. Save the settings file. The MCP server should now be available in VS Code.
+
+### Claude Desktop
+
+1. Open **Settings** → **Developer**
+2. Click **Edit Config**
+3. Open `claude_desktop_config.json`
+4. Add the following server definition for the ConfigCat MCP server:
+
+```json
+{
+  "mcpServers": {
+    "ConfigCat": {
+      "command": "npx",
+      "args": ["-y", "@configcat/mcp-server"],
+      "env": {
+        "CONFIGCAT_API_USER": "YOUR_API_USER",
+        "CONFIGCAT_API_PASS": "YOUR_API_PASSWORD"
+      }
+    }
+  }
+}
+```
+
+5. Save and restart Claude.
+
+## Available Tools
+
+### Membership Management
+
+#### Organizations
+
+- `list-organizations` - List all organizations
+
+#### Members
+
+- `list-organization-members` - List organization members
+- `list-pending-invitations` - List pending invitations
+- `list-pending-invitations-org` - List org pending invitations
+- `list-product-members` - List product members
+- `invite-member` - Invite a new member
+- `update-member-permissions` - Update the permissions of a member
+- `delete-organization-member` - Remove organization member
+- `delete-product-member` - Remove product member
+- `delete-invitation` - Cancel invitation
+
+#### Permission Groups
+
+- `list-permission-groups` - List permission groups
+- `create-permission-group` - Create a new permission group
+- `get-permission-group` - Get permission group details
+- `update-permission-group` - Update permission group
+- `delete-permission-group` - Delete permission group
+
+### General
+
+#### Products
+
+- `list-products` - List all products
+- `get-product` - Get specific product details
+- `update-product` - Update existing product
+- `delete-product` - Delete a product
+- `get-product-preferences` - Get product preferences
+- `update-product-preferences` - Update product preferences
+- `create-product` - Create a new product
+
+#### Configs
+
+- `list-configs` - List configs for a product
+- `create-config` - Create a new config
+- `get-config` - Get specific config details
+- `update-config` - Update existing config
+- `delete-config` - Delete a config
+
+#### Environments
+
+- `list-environments` - List environments for a product
+- `create-environment` - Create a new environment
+- `get-environment` - Get specific environment details
+- `update-environment` - Update existing environment
+- `delete-environment` - Delete an environment
+
+#### Segments
+
+- `list-segments` - List user segments
+- `create-segment` - Create a new segment
+- `get-segment` - Get specific segment details
+- `update-segment` - Update existing segment
+- `delete-segment` - Delete a segment
+
+#### SDK Keys
+
+- `get-sdk-keys` - Get SDK keys for config/environment
+
+#### Webhooks
+
+- `list-webhooks` - List webhooks
+- `get-webhook` - Get webhook details
+- `replace-webhook` - Replace webhook configuration
+- `update-webhook` - Update existing webhook
+- `delete-webhook` - Delete a webhook
+- `get-webhook-signing-keys` - List webhook signing keys
+- `create-webhook` - Create a new webhook
+
+#### Integrations
+
+- `list-integrations` - List integrations
+- `create-integration` - Create a new integration
+- `get-integration` - Get integration details
+- `update-integration` - Update existing integration
+- `delete-integration` - Delete an integration
+
+#### Code References
+
+- `get-code-references` - Get code references
+
+### Diagnostics
+
+#### Audit logs
+
+- `list-auditlogs` - Get product audit logs
+- `list-organization-auditlogs` - Get organization audit logs
+
+#### Zombie (stale) flags
+
+- `list-staleflags` - Get stale feature flags report
+
+### Feature Flag metadata
+
+#### Feature Flags & Settings
+
+- `list-settings` - List feature flags for a config
+- `create-setting` - Create a new feature flag
+- `get-setting` - Get specific feature flag details
+- `replace-setting` - Replace feature flag configuration
+- `update-setting` - Update existing feature flag
+- `delete-setting` - Delete a feature flag
+
+#### Tags
+
+- `list-tags` - List tags for a product
+- `create-tag` - Create a new tag
+- `list-settings-by-tag` - Get feature flags by tag
+- `get-tag` - Get specific tag details
+- `update-tag` - Update existing tag
+- `delete-tag` - Delete a tag
+
+### Feature Flag & Setting Values (v1 & v2 APIs)
+
+- `get-setting-value` - Get feature flag value
+- `update-setting-value` - Update feature flag value
+- `replace-setting-value` - Replace feature flag value
+- `get-setting-values` - Get multiple setting values
+- `post-setting-values` - Update multiple setting values
+- V2 variants: `*-v2` versions of above tools for Config V2
+
+### SDK documentation
+
+- `update-sdk-documentation` - Get comprehensive SDK documentation and code examples for seamless feature flag implementation in your project.
+
+## API Rate Limits
+
+The ConfigCat public API has rate limits. The server will respect these limits and return appropriate error messages if limits are exceeded.
+
+## Security Note
+
+This server is designed for management operations only. Do not use it for evaluating feature flag values in production applications - use the [ConfigCat SDKs](https://configcat.com/docs/sdk-reference/overview/) or [ConfigCat Proxy](https://configcat.com/docs/advanced/proxy/proxy-overview/) instead.

package/build/http.d.ts

@@ -0,0 +1,15 @@
+export type HttpOptions = {
+    baseUrl: string;
+    username: string;
+    password: string;
+    userAgent?: string;
+};
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly userAgent;
+    constructor(opts: HttpOptions);
+    request(path: string, init?: RequestInit): Promise<Response>;
+    fetch(url: string): Promise<Response>;
+}
+//# sourceMappingURL=http.d.ts.map

package/build/http.js

@@ -0,0 +1,51 @@
+import { Buffer } from "node:buffer";
+export class HttpClient {
+    baseUrl;
+    authHeader;
+    userAgent;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+        const encoded = Buffer.from(`${opts.username}:${opts.password}`).toString("base64");
+        this.authHeader = `Basic ${encoded}`;
+        this.userAgent = opts.userAgent ?? "";
+    }
+    // HTTP request with Basic auth and JSON handling
+    async request(path, init = {}) {
+        const url = path.startsWith("http") ? path : `${this.baseUrl}${path}`;
+        const headers = new Headers();
+        headers.set("Authorization", this.authHeader);
+        headers.set("Accept", "application/json");
+        headers.set("Content-Type", "application/json");
+        headers.set("User-Agent", this.userAgent);
+        // Add any additional headers from init
+        if (init.headers) {
+            const additionalHeaders = new Headers(init.headers);
+            for (const [key, value] of additionalHeaders.entries()) {
+                headers.set(key, value);
+            }
+        }
+        const response = await fetch(url, {
+            ...init,
+            headers,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            const rate = {
+                remaining: response.headers.get("X-Rate-Limit-Remaining"),
+                reset: response.headers.get("X-Rate-Limit-Reset"),
+            };
+            throw new Error(`HTTP ${response.status} ${response.statusText} for ${url} - ${text} - rate: ${JSON.stringify(rate)}`);
+        }
+        return response;
+    }
+    // Simple fetch with User-Agent header
+    async fetch(url) {
+        return await fetch(url, {
+            redirect: "follow",
+            headers: {
+                "User-Agent": this.userAgent,
+            },
+        });
+    }
+}
+//# sourceMappingURL=http.js.map

package/build/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { HttpClient } from "./http.js";
+import { registerConfigCatAPITools } from "./tools/configcat-api.js";
+import { registerConfigCatDocsTools } from "./tools/configcat-docs.js";
+const baseUrl = process.env.CONFIGCAT_BASE_URL ?? "https://api.configcat.com";
+const username = process.env.CONFIGCAT_API_USER ?? "";
+const password = process.env.CONFIGCAT_API_PASS ?? "";
+const serverName = "ConfigCat MCP";
+const serverVersion = "0.1.2";
+const http = new HttpClient({ baseUrl, username, password, userAgent: `${serverName}/${serverVersion}` });
+const server = new McpServer({ name: serverName, version: serverVersion }, { capabilities: { tools: {} } });
+async function main() {
+    if (!username || !password) {
+        throw new Error("Please set CONFIGCAT_API_USER and CONFIGCAT_API_PASS environment variables (Public API credentials). You can create your credentials on the Public API credentials management page: https://app.configcat.com/my-account/public-api-credentials.");
+    }
+    registerConfigCatAPITools(server, http);
+    await registerConfigCatDocsTools(server, http);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/tools/configcat-api.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HttpClient } from "../http";
+/**
+ * Registers the ConfigCat API tools with the given server and HTTP client.
+ *
+ * @param server The server instance to register the tools with.
+ * @param http The HTTP client instance to use for API requests.
+ */
+export declare function registerConfigCatAPITools(server: McpServer, http: HttpClient): void;
+//# sourceMappingURL=configcat-api.d.ts.map