strapi-mcp-connect 1.0.6 → 1.0.7

package/README.md

@@ -1,51 +1,94 @@
-# strapi-connect-mcp
+# strapi-mcp-connect
 
-[![npm version](https://img.shields.io/npm/v/strapi-connect-mcp.svg)](https://www.npmjs.com/package/strapi-connect-mcp)
-[![npm downloads](https://img.shields.io/npm/dt/strapi-connect-mcp.svg)](https://www.npmjs.com/package/strapi-connect-mcp)
+[![npm version](https://img.shields.io/npm/v/strapi-mcp-connect.svg)](https://www.npmjs.com/package/strapi-mcp-connect)
+[![npm downloads](https://img.shields.io/npm/dt/strapi-mcp-connect.svg)](https://www.npmjs.com/package/strapi-mcp-connect)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 [![Strapi Compatibility](https://img.shields.io/badge/Strapi-v4%20%7C%20v5-blue.svg)](https://strapi.io)
 [![MCP Version](https://img.shields.io/badge/MCP-1.13.0-purple.svg)](https://modelcontextprotocol.io)
 
-An enterprise-ready **Model Context Protocol (MCP)** server that connects AI assistants (**Claude Desktop, Cursor, VS Code, Windsurf, Claude Code, and Antigravity**) directly to your **Strapi Headless CMS**.
+An enterprise-ready **Model Context Protocol (MCP) server** that connects AI assistants such as **Claude Desktop, Cursor, VS Code, Windsurf, Claude Code, and Antigravity** directly to your **Strapi Headless CMS**.
 
-Empower your LLM to perform CRUD operations, inspect and update Single & Collection Types, filter, paginate, deeply populate relations/media, and manage draft/published content seamlessly using natural language.
+Use natural-language requests to work with Strapi content through MCP tools for CRUD operations, Single Types, Collection Types, filtering, pagination, relations, media population, and draft/published content workflows.
 
 ---
 
 ## 🏛️ Architecture & How It Works
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
 │                  AI Client / Assistant                      │
-│     (Claude Desktop, Cursor IDE, VS Code, Windsurf)         │
+│     Claude Desktop • Cursor • VS Code • Windsurf • etc.    │
 └──────────────────────────────┬──────────────────────────────┘
                                │  Standard I/O (stdio)
                                │  JSON-RPC MCP Protocol
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
-│                 strapi-connect-mcp                          │
-│        (Type-Safe Zod Schema & Validation Engine)           │
+│                    strapi-mcp-connect                        │
+│          Type-Safe Zod Schema & Validation Engine           │
 └──────────────────────────────┬──────────────────────────────┘
                                │  Authenticated REST API
-                               │  (Bearer Token / API Key)
+                               │  Bearer Token / API Token
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                     Strapi CMS (v4 / v5)                    │
-│                 (http://localhost:1337)                     │
+│                  http://localhost:1337                      │
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Request Flow
+
+```text
+Natural-language request
+        ↓
+AI Client / Assistant
+        ↓
+MCP Tool Selection
+        ↓
+Schema Validation
+        ↓
+Strapi REST API
+        ↓
+Create / Read / Update / Delete / Publish
+        ↓
+Result returned to the AI client
+```
+
 ---
 
 ## ✨ Key Highlights
 
-- ⚡ **Zero Installation (`npx`)**: Run instantly in any MCP-compatible client without manual downloads or repository cloning.
-- 📦 **Full Collection CRUD**: Complete create, read, update, and delete support across all collection types.
-- 📄 **Native Single Types**: First-class support for single types (e.g. `homepage`, `navigation`, `footer`, `global`).
-- 🚀 **Strapi v5 & v4 Ready**: Fully supports Strapi v5 `documentId` identifiers and `draft` / `published` workflows alongside classic numeric IDs.
-- 🔗 **Deep Population & Filters**: Filter queries, sorting parameters, and `populate=*` for nested relations and media fields.
-- 🛡️ **Type-Safe Validation**: Built on top of Zod schemas and official Model Context Protocol SDK.
+- ⚡ **Zero-Clone Setup with `npx`**: Run the MCP server directly without manually downloading or cloning the repository.
+- 📦 **Full Collection CRUD**: Complete create, read, update, and delete support across Collection Types.
+- 📄 **Native Single Types**: First-class support for Single Types such as `homepage`, `navigation`, `footer`, and `global`.
+- 🚀 **Strapi v4 & v5 Ready**: Supports Strapi v4 numeric IDs and Strapi v5 `documentId`-based content workflows.
+- 🔗 **Deep Population & Filters**: Supports filtering, sorting, pagination, relations, and media population such as `populate=*`.
+- 🛡️ **Type-Safe Validation**: Built with the Model Context Protocol TypeScript SDK and Zod schemas.
+- 🔐 **Token-Based Authentication**: Uses a Strapi API Token for authenticated REST API access.
+
+---
+
+## 📦 Installation
+
+### Install from npm
+
+```bash
+npm install strapi-mcp-connect
+```
+
+### Run directly with `npx`
+
+```bash
+npx -y strapi-mcp-connect
+```
+
+### CLI command
+
+The executable exposed by the package is:
+
+```bash
+strapi-connect-mcp
+```
 
 ---
 
@@ -53,18 +96,37 @@ Empower your LLM to perform CRUD operations, inspect and update Single & Collect
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `STRAPI_URL` | **Yes** | `http://localhost:1337` | The base URL of your Strapi CMS (e.g. `http://localhost:1337` or `https://cms.yourdomain.com`). |
-| `STRAPI_API_TOKEN` | **Yes** | *(empty)* | Full-access or custom API Token generated from your Strapi Admin Panel. |
+| `STRAPI_URL` | **Yes** | `http://localhost:1337` | Base URL of your Strapi CMS. |
+| `STRAPI_API_TOKEN` | **Yes** | — | Strapi API Token used to authenticate REST API requests. |
+
+Example:
+
+```env
+STRAPI_URL=http://localhost:1337
+STRAPI_API_TOKEN=YOUR_STRAPI_API_TOKEN
+```
+
+> **Security:** Never commit real Strapi API tokens to GitHub or hard-code them in source code. Use environment variables or your AI client's secure environment configuration.
 
 ---
 
-## 🚀 Quick Setup Guide (All AI Clients)
+# 🚀 Quick Setup Guide
+
+## 1. Claude Desktop
+
+Add this configuration to your Claude Desktop configuration file.
 
-### 1. Claude Desktop
+**Windows**
 
-Add this configuration to your Claude Desktop config:
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+```text
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+**macOS**
+
+```text
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
 
 ```json
 {
@@ -73,7 +135,7 @@ Add this configuration to your Claude Desktop config:
       "command": "npx",
       "args": [
         "-y",
-        "strapi-connect-mcp"
+        "strapi-mcp-connect"
       ],
       "env": {
         "STRAPI_URL": "http://localhost:1337",
@@ -84,11 +146,13 @@ Add this configuration to your Claude Desktop config:
 }
 ```
 
+Restart Claude Desktop after changing the configuration.
+
 ---
 
-### 2. Cursor IDE
+## 2. Cursor IDE
 
-1. Navigate to **Cursor Settings** $\rightarrow$ **Features** $\rightarrow$ **MCP** (or create `.cursor/mcp.json` in your project root):
+Open **Cursor Settings → Features → MCP**, or configure MCP in your project using `.cursor/mcp.json`.
 
 ```json
 {
@@ -97,7 +161,7 @@ Add this configuration to your Claude Desktop config:
       "command": "npx",
       "args": [
         "-y",
-        "strapi-connect-mcp"
+        "strapi-mcp-connect"
       ],
       "env": {
         "STRAPI_URL": "http://localhost:1337",
@@ -110,9 +174,13 @@ Add this configuration to your Claude Desktop config:
 
 ---
 
-### 3. Windsurf IDE
+## 3. Windsurf IDE
+
+Add the server to:
 
-Add to `~/.codeium/windsurf/mcp_config.json`:
+```text
+~/.codeium/windsurf/mcp_config.json
+```
 
 ```json
 {
@@ -121,7 +189,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
       "command": "npx",
       "args": [
         "-y",
-        "strapi-connect-mcp"
+        "strapi-mcp-connect"
       ],
       "env": {
         "STRAPI_URL": "http://localhost:1337",
@@ -134,9 +202,9 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ---
 
-### 4. VS Code (Cline / Roo Code / Copilot MCP)
+## 4. VS Code
 
-Add to your workspace `.vscode/mcp.json` or settings:
+For MCP-compatible VS Code clients or extensions, configure the server in `.vscode/mcp.json` when supported:
 
 ```json
 {
@@ -146,7 +214,7 @@ Add to your workspace `.vscode/mcp.json` or settings:
       "command": "npx",
       "args": [
         "-y",
-        "strapi-connect-mcp"
+        "strapi-mcp-connect"
       ],
       "env": {
         "STRAPI_URL": "http://localhost:1337",
@@ -159,9 +227,13 @@ Add to your workspace `.vscode/mcp.json` or settings:
 
 ---
 
-### 5. Antigravity IDE
+## 5. Antigravity IDE
 
-Add to your global or workspace configuration (`~/.gemini/config/mcp_config.json`):
+Add to your global or workspace MCP configuration:
+
+```text
+~/.gemini/config/mcp_config.json
+```
 
 ```json
 {
@@ -170,7 +242,7 @@ Add to your global or workspace configuration (`~/.gemini/config/mcp_config.json
       "command": "npx",
       "args": [
         "-y",
-        "strapi-connect-mcp"
+        "strapi-mcp-connect"
       ],
       "env": {
         "STRAPI_URL": "http://localhost:1337",
@@ -183,35 +255,38 @@ Add to your global or workspace configuration (`~/.gemini/config/mcp_config.json
 
 ---
 
-### 6. Claude Code CLI
+## 6. Claude Code CLI
+
+Add the MCP server with:
 
 ```bash
-claude mcp add strapi -- npx -y strapi-connect-mcp
+claude mcp add strapi -- npx -y strapi-mcp-connect
 ```
 
-
 ---
 
-## 🛠️ Available MCP Tools & Parameters
+# 🛠️ Available MCP Tools & Parameters
 
 | Tool | Purpose | Parameters |
 |---|---|---|
-| **`test_connection`** | Verifies Strapi instance health and token validity. | *(None)* |
-| **`get_entries`** | Fetch collection entries with pagination, sorting, filters, populate & status. | `pluralApiId`, `page`, `pageSize`, `filters`, `populate`, `sort`, `status` |
-| **`get_entry`** | Fetch a single collection entry by `id` or `documentId`. | `pluralApiId`, `id`, `populate`, `status` |
-| **`get_single_type`** | Fetch single type content (e.g. `homepage`, `footer`). | `singularApiId`, `populate`, `status` |
-| **`update_single_type`** | Update single type content. | `singularApiId`, `data` |
-| **`create_entry`** | Create a new entry in a collection. | `pluralApiId`, `data`, `status` |
-| **`update_entry`** | Modify an existing collection entry. | `pluralApiId`, `id`, `data` |
-| **`delete_entry`** | Permanently delete a collection entry. | `pluralApiId`, `id` |
-| **`raw_query`** | Execute direct requests on any custom Strapi endpoint. | `endpoint`, `method`, `body` |
+| **`test_connection`** | Verifies Strapi availability and token authentication. | None |
+| **`get_entries`** | Fetches Collection Type entries with pagination, sorting, filters, population, and status. | `pluralApiId`, `page`, `pageSize`, `filters`, `populate`, `sort`, `status` |
+| **`get_entry`** | Fetches a Collection Type entry by `id` or `documentId`. | `pluralApiId`, `id`, `populate`, `status` |
+| **`get_single_type`** | Fetches Single Type content such as `homepage` or `footer`. | `singularApiId`, `populate`, `status` |
+| **`update_single_type`** | Updates Single Type content. | `singularApiId`, `data` |
+| **`create_entry`** | Creates a new Collection Type entry. | `pluralApiId`, `data`, `status` |
+| **`update_entry`** | Updates an existing Collection Type entry. | `pluralApiId`, `id`, `data` |
+| **`delete_entry`** | Deletes a Collection Type entry. | `pluralApiId`, `id` |
+| **`raw_query`** | Sends a direct request to a custom Strapi endpoint. | `endpoint`, `method`, `body` |
 
 ---
 
-## 💡 Practical Examples
+# 💡 Practical Examples
+
+## 1. Fetch entries with relations
 
-### 1. Fetching Entries with Relations
 **Tool:** `get_entries`
+
 ```json
 {
   "pluralApiId": "articles",
@@ -221,8 +296,10 @@ claude mcp add strapi -- npx -y strapi-connect-mcp
 }
 ```
 
-### 2. Creating a Published Entry
+## 2. Create a published entry
+
 **Tool:** `create_entry`
+
 ```json
 {
   "pluralApiId": "pages",
@@ -235,8 +312,10 @@ claude mcp add strapi -- npx -y strapi-connect-mcp
 }
 ```
 
-### 3. Fetching a Single Type
+## 3. Fetch a Single Type
+
 **Tool:** `get_single_type`
+
 ```json
 {
   "singularApiId": "homepage",
@@ -246,61 +325,125 @@ claude mcp add strapi -- npx -y strapi-connect-mcp
 
 ---
 
-## 🔑 Generating Your Strapi API Token
+# 🔑 Generating Your Strapi API Token
+
+1. Open your Strapi Admin Panel:
+   ```text
+   http://localhost:1337/admin
+   ```
+2. Go to **Settings → API Tokens**.
+3. Click **Create new API Token**.
+4. Use a name such as:
+   ```text
+   MCP Connector
+   ```
+5. Choose the permissions required for your content operations.
+6. Save the token and copy it securely.
+
+Then configure:
+
+```env
+STRAPI_API_TOKEN=YOUR_STRAPI_API_TOKEN
+```
+
+> For production environments, use the minimum permissions required for the workflow instead of granting unnecessary access.
+
+---
+
+# 💬 Natural Language Prompt Examples
+
+After configuration, you can ask your AI assistant:
+
+```text
+List all entries from my articles collection in Strapi.
+```
+
+```text
+Fetch the homepage single type content and summarize it.
+```
+
+```text
+Create a new product in Strapi with title "Wireless Headphones" and price 149.
+```
+
+```text
+Update the about-page entry and change the contact email.
+```
+
+```text
+Find all draft pages in Strapi.
+```
 
-1. Open your Strapi Admin Panel (`http://localhost:1337/admin`).
-2. Go to **Settings** $\rightarrow$ **API Tokens** $\rightarrow$ Click **Create new API Token**.
-3. Choose:
-   - **Name:** `MCP Connector`
-   - **Token duration:** `Unlimited`
-   - **Token type:** `Full access` *(or configure granular permissions)*
-4. Click **Save** and copy the generated token into your MCP configuration.
+```text
+Create a 2BHK property in Ahmedabad with a price of 45 lakh.
+```
 
 ---
 
-## 💬 Natural Language Prompt Examples
+# 🔐 Security & Permissions
 
-Once configured, simply talk to your AI assistant:
+This MCP server communicates with Strapi through authenticated REST API requests.
 
-- *"List all entries from my **articles** collection in Strapi."*
-- *"Fetch the **homepage** single type content and summarize it."*
-- *"Create a new product in Strapi with title 'Wireless Headphones' and price 149."*
-- *"Update the **about-page** entry to change the contact email."*
-- *"Find all draft pages in Strapi."*
+Recommended practices:
+
+- Never hard-code Strapi API tokens in source code.
+- Never commit `.env` files containing real credentials.
+- Grant only the Strapi permissions required by your workflow.
+- Keep production credentials separate from local development credentials.
+- Review `raw_query` usage carefully because it can access custom endpoints supported by the configured token.
 
 ---
 
-## ❓ Troubleshooting & FAQs
+# ❓ Troubleshooting & FAQs
 
 | Issue | Root Cause | Solution |
 |---|---|---|
-| **401 Unauthorized** | Invalid, expired, or missing Strapi API Token. | Generate a fresh Full Access token in Strapi Admin $\rightarrow$ Settings $\rightarrow$ API Tokens and update your MCP configuration. |
-| **404 Not Found** | Incorrect collection name or Plural API ID. | Check the exact **Plural API ID** in Strapi Admin $\rightarrow$ Content-Type Builder (e.g. use `pages`, `articles`, `products`). |
-| **Connection Refused** | Strapi server is not running or URL is wrong. | Ensure `npm run dev` is active in your Strapi project and `STRAPI_URL` points to `http://localhost:1337`. |
-| **Tools Not Showing** | Config syntax error or editor wasn't restarted. | Verify JSON syntax and fully restart your AI editor (check background processes). |
+| **401 Unauthorized** | Invalid, expired, or missing Strapi API Token. | Generate a valid API token and update `STRAPI_API_TOKEN`. |
+| **403 Forbidden** | The token does not have sufficient permissions. | Update the token permissions for the required content type/action. |
+| **404 Not Found** | Incorrect Collection Type name, Single Type name, or endpoint. | Verify the exact API ID in Strapi. |
+| **Connection Refused** | Strapi is not running or `STRAPI_URL` is incorrect. | Start Strapi and verify the configured URL. |
+| **Tools Not Showing** | MCP configuration is incorrect or the AI client has not reloaded the server. | Check the JSON configuration and restart the AI client. |
+| **Invalid Data** | Request fields do not match the Strapi content-type schema. | Check the content-type schema and provide the correct fields. |
+
+---
+
+# 🗺️ Roadmap
+
+- [ ] Automated Schema & Content-Type Discovery
+- [ ] GraphQL query execution support
+- [ ] Advanced Strapi Media Library management
+- [ ] Batch entry creation & bulk updates
+- [ ] More granular permission-aware tool discovery
 
 ---
 
-## 🗺️ Roadmap
+# ⚠️ Known Limitations
 
-- [ ] Automated Schema & Content-Type Discovery (auto-detect all plural and singular API IDs).
-- [ ] GraphQL query execution support.
-- [ ] Advanced Strapi Media Library management integration.
-- [ ] Batch entry creation & bulk updates.
+- **REST API Dependency:** This MCP server communicates with Strapi through the REST API.
+- **Permissions:** Available operations depend on the permissions assigned to the configured Strapi API Token.
+- **Custom Plugins:** Custom plugins with non-standard route structures can be accessed using `raw_query` when the token has sufficient permissions.
+- **Schema Discovery:** Automated schema and Content-Type discovery is planned for a future release.
 
 ---
 
-## ⚠️ Known Limitations
+# 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome.
 
-- **REST API Dependency:** This MCP server communicates via Strapi's standard REST API. Ensure the REST endpoints are enabled in your Strapi project.
-- **Permissions:** Operations depend on the permissions assigned to your Strapi API Token. If a tool fails with `403 Forbidden`, ensure the token has sufficient permissions for that content type in Strapi Admin $\rightarrow$ Settings $\rightarrow$ API Tokens.
-- **Custom Plugins:** Custom plugins with non-standard API route structures can be accessed using the `raw_query` tool.
+1. Fork the repository.
+2. Create a feature branch.
+3. Make your changes.
+4. Run the build.
+5. Verify the MCP server locally.
+6. Open a pull request.
 
 ---
 
-## 📄 License
+# 📄 License
 
 Distributed under the **MIT License**.
 
-Authored with ❤️ by **[Kevin-patel](https://github.com/kevinpateldevelopment)**
+Authored with ❤️ by **Kevin Patel**
 
+- GitHub: https://github.com/kevinpateldevelopment
+- npm: https://www.npmjs.com/package/strapi-mcp-connect

package/package.json

@@ -1,6 +1,6 @@
 {
-  "name":"strapi-mcp-connect",
-  "version": "1.0.6",
+  "name": "strapi-mcp-connect",
+  "version": "1.0.7",
   "description": "Model Context Protocol (MCP) server for Strapi CMS. Connects Claude Desktop, Cursor, VS Code, and AI IDEs to Strapi REST API.",
   "type": "module",
   "main": "build/index.js",