@contentful/mcp-tools 0.1.0-dev-20251016T1739-07b05ef.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +168 -0
  2. package/package.json +62 -0
package/README.md ADDED
@@ -0,0 +1,168 @@
1
+ # @contentful/mcp-tools
2
+
3
+ A toolkit package containing reusable MCP (Model Context Protocol) tools for Contentful. This package provides structured tool collections with complete metadata including descriptions, input schemas, semantic annotations, and tool implementations.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @contentful/mcp-tools
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ### Using Tool Collections
14
+
15
+ The package exports tool collections organized by category. Each tool in a collection includes:
16
+
17
+ - `title`: The tool name
18
+ - `description`: What the tool does
19
+ - `inputParams`: Zod schema for input validation
20
+ - `annotations`: Semantic hints about tool behavior (readOnly, destructive, idempotent, openWorld)
21
+ - `tool`: The actual tool implementation function
22
+
23
+ ```typescript
24
+ import { entryTools, assetTools, contextTools } from '@contentful/mcp-tools';
25
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
26
+
27
+ const server = new McpServer();
28
+
29
+ // Register a specific tool
30
+ const { searchEntries } = entryTools;
31
+ server.registerTool(
32
+ searchEntries.title,
33
+ {
34
+ description: searchEntries.description,
35
+ inputSchema: searchEntries.inputParams,
36
+ annotations: searchEntries.annotations,
37
+ },
38
+ searchEntries.tool,
39
+ );
40
+
41
+ // Register all tools from a collection
42
+ Object.values(assetTools).forEach((toolConfig) => {
43
+ server.registerTool(
44
+ toolConfig.title,
45
+ {
46
+ description: toolConfig.description,
47
+ inputSchema: toolConfig.inputParams,
48
+ annotations: toolConfig.annotations,
49
+ },
50
+ toolConfig.tool,
51
+ );
52
+ });
53
+ ```
54
+
55
+ ### Available Tool Collections
56
+
57
+ ```typescript
58
+ import {
59
+ aiActionTools, // AI action management
60
+ assetTools, // Asset operations
61
+ contentTypeTools, // Content type management
62
+ contextTools, // Initial context setup
63
+ entryTools, // Entry operations
64
+ environmentTools, // Environment management
65
+ jobTools, // Long-running jobs
66
+ localeTools, // Locale management
67
+ orgTools, // Organization operations
68
+ spaceTools, // Space operations
69
+ tagTools, // Tag management
70
+ taxonomyTools, // Taxonomy/concept scheme operations
71
+ } from '@contentful/mcp-tools';
72
+ ```
73
+
74
+ ### Tool Annotations
75
+
76
+ Each tool includes semantic annotations to help MCP clients understand tool behavior:
77
+
78
+ - **`readOnlyHint`**: `true` if the tool only reads data without modifications
79
+ - **`destructiveHint`**: `true` if the tool permanently deletes or removes data
80
+ - **`idempotentHint`**: `true` if calling the tool multiple times with the same input produces the same result
81
+ - **`openWorldHint`**: `true` if the tool interacts with external services or systems beyond Contentful
82
+
83
+ ## 🛠️ Available Tools
84
+
85
+ | Category | Tool Name | Description |
86
+ | ------------------------- | ---------------------------------- | ------------------------------------------------ |
87
+ | **Context & Setup** | `get_initial_context` | Initialize connection and get usage instructions |
88
+ | **Content Types** | `list_content_types` | List content types (max 10 per request) |
89
+ | | `get_content_type` | Get detailed content type information |
90
+ | | `create_content_type` | Create new content types |
91
+ | | `update_content_type` | Modify existing content types |
92
+ | | `publish_content_type` | Publish content type changes |
93
+ | | `unpublish_content_type` | Unpublish content types |
94
+ | | `delete_content_type` | Remove content types |
95
+ | **Entries** | `search_entries` | Search and filter entries in your space |
96
+ | | `get_entry` | Retrieve specific entries |
97
+ | | `create_entry` | Create new content entries with locale support |
98
+ | | `update_entry` | Modify existing entries with locale support |
99
+ | | `publish_entry` | Publish entries (single or bulk up to 100) |
100
+ | | `unpublish_entry` | Unpublish entries (single or bulk up to 100) |
101
+ | | `delete_entry` | Remove entries |
102
+ | **Assets** | `upload_asset` | Upload new assets |
103
+ | | `list_assets` | List and browse assets (max 3 per request) |
104
+ | | `get_asset` | Retrieve specific assets |
105
+ | | `update_asset` | Modify asset metadata |
106
+ | | `publish_asset` | Publish assets (single or bulk up to 100) |
107
+ | | `unpublish_asset` | Unpublish assets (single or bulk up to 100) |
108
+ | | `delete_asset` | Remove assets |
109
+ | **Spaces & Environments** | `list_spaces` | List available spaces (max 10 per request) |
110
+ | | `get_space` | Get space details |
111
+ | | `list_environments` | List environments in a space |
112
+ | | `create_environment` | Create new environments |
113
+ | | `delete_environment` | Remove environments |
114
+ | **Locales** | `list_locales` | List all locales in your environment |
115
+ | | `get_locale` | Retrieve specific locale information |
116
+ | | `create_locale` | Create new locales for multi-language content |
117
+ | | `update_locale` | Modify existing locale settings |
118
+ | | `delete_locale` | Remove locales from environment |
119
+ | **Tags** | `list_tags` | List all tags in an environment |
120
+ | | `create_tag` | Create new tags with public/private visibility |
121
+ | **Organizations** | `list_orgs` | List organizations user has access to |
122
+ | | `get_org` | Get details of a specific organization |
123
+ | **AI Actions** | `create_ai_action` | Create custom AI-powered workflows |
124
+ | | `invoke_ai_action` | Invoke AI action with variables (bulk support) |
125
+ | | `get_ai_action_invocation` | Get AI action invocation details |
126
+ | | `get_ai_action` | Retrieve AI action details and configuration |
127
+ | | `list_ai_actions` | List AI actions in a space (max 3 per request) |
128
+ | | `update_ai_action` | Update existing AI actions |
129
+ | | `publish_ai_action` | Publish AI actions for use |
130
+ | | `unpublish_ai_action` | Unpublish AI actions |
131
+ | | `delete_ai_action` | Remove AI actions |
132
+ | **Taxonomy Concepts** | `create_concept` | Create new taxonomy concepts with localization |
133
+ | | `get_concept` | Retrieve specific taxonomy concept |
134
+ | | `list_concepts` | List concepts with filtering and hierarchy |
135
+ | | `update_concept` | Update taxonomy concept properties |
136
+ | | `delete_concept` | Remove taxonomy concepts |
137
+ | **Taxonomy Schemes** | `create_concept_scheme` | Create new taxonomy concept schemes |
138
+ | | `get_concept_scheme` | Retrieve specific concept scheme |
139
+ | | `list_concept_schemes` | List concept schemes with pagination |
140
+ | | `update_concept_scheme` | Update concept scheme properties |
141
+ | | `delete_concept_scheme` | Remove concept schemes |
142
+ | **Space Migration** | `space_to_space_migration_handler` | Enable/disable space migration workflow |
143
+ | | `space_to_space_param_collection` | Collect parameters for migration workflow |
144
+ | | `export_space` | Export space to file for migration |
145
+ | | `import_space` | Import space from exported file |
146
+
147
+ ## Configuration
148
+
149
+ The tools require environment variables to be configured:
150
+
151
+ ```bash
152
+ CONTENTFUL_MANAGEMENT_ACCESS_TOKEN=your_token_here
153
+ CONTENTFUL_HOST=api.contentful.com
154
+ SPACE_ID=your_space_id
155
+ ENVIRONMENT_ID=master
156
+ ```
157
+
158
+ ## Testing
159
+
160
+ All tools include comprehensive unit tests. Run tests with:
161
+
162
+ ```bash
163
+ npm test
164
+ ```
165
+
166
+ ## License
167
+
168
+ MIT
package/package.json ADDED
@@ -0,0 +1,62 @@
1
+ {
2
+ "name": "@contentful/mcp-tools",
3
+ "version": "0.1.0-dev-20251016T1739-07b05ef.0",
4
+ "type": "module",
5
+ "main": "./dist/index.js",
6
+ "module": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
+ "exports": {
9
+ "./package.json": "./package.json",
10
+ ".": {
11
+ "@contentful/mcp-server": "./src/index.ts",
12
+ "types": "./dist/index.d.ts",
13
+ "import": "./dist/index.js",
14
+ "default": "./dist/index.js"
15
+ }
16
+ },
17
+ "files": [
18
+ "dist",
19
+ "package.json",
20
+ "README.md",
21
+ "LICENSE"
22
+ ],
23
+ "scripts": {
24
+ "prebuild": "npm run clean",
25
+ "build": "tsup",
26
+ "clean": "rimraf dist",
27
+ "dev": "tsup --watch",
28
+ "test": "vitest",
29
+ "test:run": "vitest run",
30
+ "format": "prettier --check \"**/*.{ts,js,json,md}\"",
31
+ "format:fix": "prettier --write \"**/*.{ts,js,json,md}\"",
32
+ "lint": "eslint --ext .ts,.js .",
33
+ "lint:fix": "eslint --ext .ts,.js . --fix"
34
+ },
35
+ "author": "Contentful GmbH",
36
+ "license": "MIT",
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "git+https://github.com/contentful/contentful-mcp-server.git",
40
+ "directory": "packages/mcp-tools"
41
+ },
42
+ "dependencies": {
43
+ "@modelcontextprotocol/sdk": "^1.17.0",
44
+ "contentful-export": "^7.21.78",
45
+ "contentful-import": "^9.4.111",
46
+ "contentful-management": "^11.54.3",
47
+ "dotenv": "^16.4.7",
48
+ "fast-xml-parser": "^5.2.5",
49
+ "outdent": "^0.8.0",
50
+ "@contentful/rich-text-types": "^16.8.5",
51
+ "tsup": "^8.5.0",
52
+ "vitest": "^3.2.4",
53
+ "zod": "^3.25.76"
54
+ },
55
+ "devDependencies": {
56
+ "@types/node": "^22.16.5",
57
+ "eslint": "^9.35.0",
58
+ "prettier": "^3.6.2",
59
+ "rimraf": "^6.0.1",
60
+ "typescript": "^5.8.2"
61
+ }
62
+ }