directify-mcp 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/README.md

@@ -0,0 +1,172 @@
+# Directify MCP Server
+
+[MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for [Directify](https://directify.app) - manage your directory websites through AI assistants like Claude, Cursor, and other MCP-compatible tools.
+
+## What is this?
+
+This MCP server lets AI assistants directly manage your Directify directories. Ask Claude to create listings, update categories, publish articles, and more - all through natural language.
+
+## Installation
+
+```bash
+npm install -g directify-mcp
+```
+
+## Setup
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "directify": {
+      "command": "npx",
+      "args": ["-y", "directify-mcp"],
+      "env": {
+        "DIRECTIFY_API_TOKEN": "your-api-token-here",
+        "DIRECTIFY_DIRECTORY_ID": "123"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add directify -- npx -y directify-mcp
+
+# Then set environment variables in your shell:
+export DIRECTIFY_API_TOKEN="your-api-token-here"
+export DIRECTIFY_DIRECTORY_ID="123"
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "directify": {
+      "command": "npx",
+      "args": ["-y", "directify-mcp"],
+      "env": {
+        "DIRECTIFY_API_TOKEN": "your-api-token-here",
+        "DIRECTIFY_DIRECTORY_ID": "123"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Environment Variable | Required | Description |
+|---------------------|----------|-------------|
+| `DIRECTIFY_API_TOKEN` | Yes | Your API token from Settings > API |
+| `DIRECTIFY_DIRECTORY_ID` | No | Default directory ID (can also pass per-tool) |
+
+### Getting your API token
+
+1. Go to your [Directify dashboard](https://directify.app)
+2. Navigate to **Settings > API**
+3. Click the **Key icon** to generate a new token
+4. Copy the token
+
+### Finding your Directory ID
+
+Ask Claude: *"List my Directify directories"* - or find it in the URL when viewing your directory in the dashboard (`/app/{directory_id}/...`).
+
+## Available Tools
+
+### Directories
+
+| Tool | Description |
+|------|-------------|
+| `list_directories` | List all directories you own |
+
+### Categories
+
+| Tool | Description |
+|------|-------------|
+| `list_categories` | List all categories in a directory |
+| `get_category` | Get details of a specific category |
+| `create_category` | Create a new category |
+| `update_category` | Update a category |
+| `delete_category` | Delete a category |
+
+### Tags
+
+| Tool | Description |
+|------|-------------|
+| `list_tags` | List all tags |
+| `get_tag` | Get a specific tag |
+| `create_tag` | Create a new tag |
+| `update_tag` | Update a tag |
+| `delete_tag` | Delete a tag |
+
+### Custom Fields
+
+| Tool | Description |
+|------|-------------|
+| `list_custom_fields` | List all custom fields (useful to know field names for listings) |
+
+### Listings
+
+| Tool | Description |
+|------|-------------|
+| `list_listings` | List all listings (paginated) |
+| `get_listing` | Get full listing details with custom fields |
+| `create_listing` | Create a new listing with custom field values |
+| `update_listing` | Update a listing |
+| `delete_listing` | Delete a listing |
+| `check_listing_exists` | Check if a URL already exists |
+| `bulk_create_listings` | Create up to 100 listings at once |
+
+### Articles
+
+| Tool | Description |
+|------|-------------|
+| `list_articles` | List all blog articles (paginated) |
+| `get_article` | Get article details |
+| `create_article` | Create a new article (HTML or Markdown) |
+| `update_article` | Update an article |
+| `delete_article` | Delete an article |
+| `toggle_article` | Toggle active/inactive status |
+
+## Example Conversations
+
+### Create a listing
+
+> **You:** Add a new restaurant called "Bella Trattoria" at 123 Main St, Italian cuisine, price range $$$, open Mon-Sat 11am-10pm.
+
+Claude will use `create_listing` with the appropriate fields.
+
+### Bulk import
+
+> **You:** Create 5 test listings for Japanese restaurants in San Francisco with different names and addresses.
+
+Claude will use `bulk_create_listings` to create all 5 at once.
+
+### Manage content
+
+> **You:** Write a blog article about the top 10 Italian restaurants and publish it.
+
+Claude will use `create_article` with markdown content.
+
+### Update listings
+
+> **You:** Update all listings that don't have a description and add a short one based on their name and category.
+
+Claude will use `list_listings`, then `update_listing` for each one.
+
+## Rate Limits
+
+The Directify API allows **120 requests per minute** per directory. The MCP server handles rate limit errors gracefully and will inform the AI assistant to retry.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "directify-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Directify - manage your directory websites through AI assistants like Claude.",
+  "main": "src/index.js",
+  "bin": {
+    "directify-mcp": "./src/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "directify",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "directory",
+    "listings",
+    "api"
+  ],
+  "author": "Directify",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,77 @@
+const BASE_URL = 'https://directify.app/api';
+
+export function getConfig() {
+  const token = process.env.DIRECTIFY_API_TOKEN;
+  const directoryId = process.env.DIRECTIFY_DIRECTORY_ID;
+
+  if (!token) {
+    throw new Error('DIRECTIFY_API_TOKEN environment variable is required');
+  }
+
+  return { token, directoryId };
+}
+
+export function resolveDirectory(directoryId) {
+  const dir = directoryId || getConfig().directoryId;
+  if (!dir) {
+    throw new Error(
+      'No directory ID provided. Pass directory_id parameter or set DIRECTIFY_DIRECTORY_ID environment variable.'
+    );
+  }
+  return dir;
+}
+
+async function request(method, path, body = null) {
+  const { token } = getConfig();
+
+  const url = `${BASE_URL}${path}`;
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+  };
+
+  const options = { method, headers };
+  if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+    options.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, options);
+
+  if (res.status === 401) {
+    throw new Error('Authentication failed. Check your DIRECTIFY_API_TOKEN.');
+  }
+  if (res.status === 403) {
+    throw new Error('Access denied. You do not have permission to access this resource.');
+  }
+  if (res.status === 404) {
+    throw new Error('Resource not found.');
+  }
+  if (res.status === 422) {
+    const data = await res.json();
+    const errors = data.errors
+      ? Object.entries(data.errors)
+          .map(([field, msgs]) => `${field}: ${Array.isArray(msgs) ? msgs.join(', ') : msgs}`)
+          .join('\n')
+      : data.message || 'Validation failed';
+    throw new Error(`Validation error:\n${errors}`);
+  }
+  if (res.status === 429) {
+    throw new Error('Rate limit exceeded (120 requests/minute). Please wait and retry.');
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`API error (${res.status}): ${text || res.statusText}`);
+  }
+
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+export const api = {
+  get: (path) => request('GET', path),
+  post: (path, body) => request('POST', path, body),
+  put: (path, body) => request('PUT', path, body),
+  patch: (path, body) => request('PATCH', path, body),
+  delete: (path) => request('DELETE', path),
+};

package/src/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { allTools } from './tools.js';
+
+const server = new Server(
+  { name: 'directify', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: allTools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  })),
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const tool = allTools.find((t) => t.name === name);
+
+  if (!tool) {
+    return {
+      content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+      isError: true,
+    };
+  }
+
+  try {
+    const result = await tool.handler(args || {});
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools.js

@@ -0,0 +1,624 @@
+import { api, resolveDirectory } from './api.js';
+
+// ─── Directories ───
+
+export const listDirectories = {
+  name: 'list_directories',
+  description: 'List all directories owned by the authenticated user.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+  handler: async () => {
+    const data = await api.get('/directories');
+    return data.data || data;
+  },
+};
+
+// ─── Categories ───
+
+export const listCategories = {
+  name: 'list_categories',
+  description: 'List all active categories in a directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID (optional if DIRECTIFY_DIRECTORY_ID is set)' },
+    },
+  },
+  handler: async ({ directory_id }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/categories`);
+    return data.data || data;
+  },
+};
+
+export const getCategory = {
+  name: 'get_category',
+  description: 'Get details of a specific category.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      category_id: { type: 'string', description: 'Category ID' },
+    },
+    required: ['category_id'],
+  },
+  handler: async ({ directory_id, category_id }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/categories/${category_id}`);
+    return data.data || data;
+  },
+};
+
+export const createCategory = {
+  name: 'create_category',
+  description: 'Create a new category in a directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      title: { type: 'string', description: 'Category title (required)' },
+      slug: { type: 'string', description: 'URL slug (auto-generated if not set)' },
+      description: { type: 'string', description: 'Category description' },
+      content: { type: 'string', description: 'Category content (markdown)' },
+      icon: { type: 'string', description: 'Icon (emoji or URL)' },
+      custom_icon_url: { type: 'string', description: 'Custom icon image URL' },
+      parent_id: { type: 'number', description: 'Parent category ID for nesting' },
+      is_active: { type: 'boolean', description: 'Whether the category is active (default: true)' },
+      order: { type: 'number', description: 'Sort order' },
+    },
+    required: ['title'],
+  },
+  handler: async ({ directory_id, ...body }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.post(`/directories/${dir}/categories`, body);
+    return data.data || data;
+  },
+};
+
+export const updateCategory = {
+  name: 'update_category',
+  description: 'Update an existing category.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      category_id: { type: 'string', description: 'Category ID to update' },
+      title: { type: 'string', description: 'Category title' },
+      slug: { type: 'string', description: 'URL slug' },
+      description: { type: 'string', description: 'Category description' },
+      content: { type: 'string', description: 'Category content (markdown)' },
+      icon: { type: 'string', description: 'Icon' },
+      parent_id: { type: 'number', description: 'Parent category ID' },
+      is_active: { type: 'boolean', description: 'Active status' },
+      order: { type: 'number', description: 'Sort order' },
+    },
+    required: ['category_id'],
+  },
+  handler: async ({ directory_id, category_id, ...body }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.put(`/directories/${dir}/categories/${category_id}`, body);
+    return data.data || data;
+  },
+};
+
+export const deleteCategory = {
+  name: 'delete_category',
+  description: 'Delete a category from a directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      category_id: { type: 'string', description: 'Category ID to delete' },
+    },
+    required: ['category_id'],
+  },
+  handler: async ({ directory_id, category_id }) => {
+    const dir = resolveDirectory(directory_id);
+    await api.delete(`/directories/${dir}/categories/${category_id}`);
+    return { success: true, message: `Category ${category_id} deleted.` };
+  },
+};
+
+// ─── Tags ───
+
+export const listTags = {
+  name: 'list_tags',
+  description: 'List all active tags in a directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+    },
+  },
+  handler: async ({ directory_id }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/tags`);
+    return data.data || data;
+  },
+};
+
+export const getTag = {
+  name: 'get_tag',
+  description: 'Get details of a specific tag.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      tag_id: { type: 'string', description: 'Tag ID' },
+    },
+    required: ['tag_id'],
+  },
+  handler: async ({ directory_id, tag_id }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/tags/${tag_id}`);
+    return data.data || data;
+  },
+};
+
+export const createTag = {
+  name: 'create_tag',
+  description: 'Create a new tag in a directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      title: { type: 'string', description: 'Tag title (required)' },
+      slug: { type: 'string', description: 'URL slug' },
+      color: { type: 'string', description: 'Background color (hex, e.g. #f59e0b)' },
+      text_color: { type: 'string', description: 'Text color (hex)' },
+      icon: { type: 'string', description: 'Icon' },
+      heroicon: { type: 'string', description: 'Heroicon name' },
+      is_active: { type: 'boolean', description: 'Active status (default: true)' },
+    },
+    required: ['title'],
+  },
+  handler: async ({ directory_id, ...body }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.post(`/directories/${dir}/tags`, body);
+    return data.data || data;
+  },
+};
+
+export const updateTag = {
+  name: 'update_tag',
+  description: 'Update an existing tag.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      tag_id: { type: 'string', description: 'Tag ID to update' },
+      title: { type: 'string', description: 'Tag title' },
+      slug: { type: 'string', description: 'URL slug' },
+      color: { type: 'string', description: 'Background color (hex)' },
+      text_color: { type: 'string', description: 'Text color (hex)' },
+      is_active: { type: 'boolean', description: 'Active status' },
+    },
+    required: ['tag_id'],
+  },
+  handler: async ({ directory_id, tag_id, ...body }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.put(`/directories/${dir}/tags/${tag_id}`, body);
+    return data.data || data;
+  },
+};
+
+export const deleteTag = {
+  name: 'delete_tag',
+  description: 'Delete a tag from a directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      tag_id: { type: 'string', description: 'Tag ID to delete' },
+    },
+    required: ['tag_id'],
+  },
+  handler: async ({ directory_id, tag_id }) => {
+    const dir = resolveDirectory(directory_id);
+    await api.delete(`/directories/${dir}/tags/${tag_id}`);
+    return { success: true, message: `Tag ${tag_id} deleted.` };
+  },
+};
+
+// ─── Custom Fields ───
+
+export const listCustomFields = {
+  name: 'list_custom_fields',
+  description: 'List all custom fields defined for a directory. Use this to know which field names to set when creating/updating listings.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+    },
+  },
+  handler: async ({ directory_id }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/custom-fields`);
+    return data.data || data;
+  },
+};
+
+// ─── Listings ───
+
+export const listListings = {
+  name: 'list_listings',
+  description: 'List all listings in a directory (paginated, 100 per page).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      page: { type: 'number', description: 'Page number (default: 1)' },
+    },
+  },
+  handler: async ({ directory_id, page = 1 }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/projects?page=${page}`);
+    return data;
+  },
+};
+
+export const getListing = {
+  name: 'get_listing',
+  description: 'Get full details of a specific listing, including custom field values.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      listing_id: { type: 'string', description: 'Listing ID' },
+    },
+    required: ['listing_id'],
+  },
+  handler: async ({ directory_id, listing_id }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/projects/${listing_id}`);
+    return data.data || data;
+  },
+};
+
+export const createListing = {
+  name: 'create_listing',
+  description:
+    'Create a new listing in a directory. You can include custom field values by using the field name as a key (use list_custom_fields to see available fields).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      name: { type: 'string', description: 'Listing name (required)' },
+      url: { type: 'string', description: 'Website URL' },
+      slug: { type: 'string', description: 'URL slug' },
+      description: { type: 'string', description: 'Short description' },
+      content: { type: 'string', description: 'Full content (markdown)' },
+      image_url: { type: 'string', description: 'Cover image URL' },
+      logo_url: { type: 'string', description: 'Logo URL' },
+      phone_number: { type: 'string', description: 'Phone number' },
+      email: { type: 'string', description: 'Email address' },
+      address: { type: 'string', description: 'Physical address' },
+      latitude: { type: 'number', description: 'Latitude' },
+      longitude: { type: 'number', description: 'Longitude' },
+      categories: {
+        type: 'array',
+        items: { type: 'number' },
+        description: 'Array of category IDs',
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'number' },
+        description: 'Array of tag IDs',
+      },
+      is_active: { type: 'boolean', description: 'Active status (default: true)' },
+      is_featured: { type: 'boolean', description: 'Featured status' },
+      custom_fields: {
+        type: 'object',
+        description: 'Custom field values as key-value pairs (e.g. {"price_range": "2", "cuisine_type": "Italian"})',
+        additionalProperties: true,
+      },
+    },
+    required: ['name'],
+  },
+  handler: async ({ directory_id, custom_fields, ...body }) => {
+    const dir = resolveDirectory(directory_id);
+    const payload = { ...body, ...custom_fields };
+    const data = await api.post(`/directories/${dir}/projects`, payload);
+    return data.data || data;
+  },
+};
+
+export const updateListing = {
+  name: 'update_listing',
+  description: 'Update an existing listing. Only pass fields you want to change.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      listing_id: { type: 'string', description: 'Listing ID to update' },
+      name: { type: 'string', description: 'Listing name' },
+      url: { type: 'string', description: 'Website URL' },
+      slug: { type: 'string', description: 'URL slug' },
+      description: { type: 'string', description: 'Short description' },
+      content: { type: 'string', description: 'Full content (markdown)' },
+      image_url: { type: 'string', description: 'Cover image URL' },
+      logo_url: { type: 'string', description: 'Logo URL' },
+      phone_number: { type: 'string', description: 'Phone number' },
+      email: { type: 'string', description: 'Email address' },
+      address: { type: 'string', description: 'Physical address' },
+      latitude: { type: 'number', description: 'Latitude' },
+      longitude: { type: 'number', description: 'Longitude' },
+      categories: {
+        type: 'array',
+        items: { type: 'number' },
+        description: 'Array of category IDs',
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'number' },
+        description: 'Array of tag IDs',
+      },
+      is_active: { type: 'boolean', description: 'Active status' },
+      is_featured: { type: 'boolean', description: 'Featured status' },
+      custom_fields: {
+        type: 'object',
+        description: 'Custom field values as key-value pairs',
+        additionalProperties: true,
+      },
+    },
+    required: ['listing_id'],
+  },
+  handler: async ({ directory_id, listing_id, custom_fields, ...body }) => {
+    const dir = resolveDirectory(directory_id);
+    const payload = { ...body, ...custom_fields };
+    const data = await api.put(`/directories/${dir}/projects/${listing_id}`, payload);
+    return data.data || data;
+  },
+};
+
+export const deleteListing = {
+  name: 'delete_listing',
+  description: 'Delete a listing from a directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      listing_id: { type: 'string', description: 'Listing ID to delete' },
+    },
+    required: ['listing_id'],
+  },
+  handler: async ({ directory_id, listing_id }) => {
+    const dir = resolveDirectory(directory_id);
+    await api.delete(`/directories/${dir}/projects/${listing_id}`);
+    return { success: true, message: `Listing ${listing_id} deleted.` };
+  },
+};
+
+export const checkListingExists = {
+  name: 'check_listing_exists',
+  description: 'Check if a listing with a given URL already exists in the directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      url: { type: 'string', description: 'URL to check' },
+    },
+    required: ['url'],
+  },
+  handler: async ({ directory_id, url }) => {
+    const dir = resolveDirectory(directory_id);
+    try {
+      const data = await api.post(`/directories/${dir}/projects/exists`, { url });
+      return { exists: false, message: data.message };
+    } catch (err) {
+      if (err.message.includes('already exists')) {
+        return { exists: true, message: err.message };
+      }
+      throw err;
+    }
+  },
+};
+
+export const bulkCreateListings = {
+  name: 'bulk_create_listings',
+  description: 'Create multiple listings at once (max 100 per request).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      listings: {
+        type: 'array',
+        description: 'Array of listing objects (each must have at least a "name" field)',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            url: { type: 'string' },
+            description: { type: 'string' },
+            categories: { type: 'array', items: { type: 'number' } },
+            tags: { type: 'array', items: { type: 'number' } },
+          },
+          required: ['name'],
+          additionalProperties: true,
+        },
+      },
+    },
+    required: ['listings'],
+  },
+  handler: async ({ directory_id, listings }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.post(`/directories/${dir}/projects/bulk`, { listings });
+    return data;
+  },
+};
+
+// ─── Articles ───
+
+export const listArticles = {
+  name: 'list_articles',
+  description: 'List all blog articles in a directory (paginated).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      page: { type: 'number', description: 'Page number (default: 1)' },
+    },
+  },
+  handler: async ({ directory_id, page = 1 }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/articles?page=${page}`);
+    return data;
+  },
+};
+
+export const getArticle = {
+  name: 'get_article',
+  description: 'Get full details of a specific article.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      article_id: { type: 'string', description: 'Article ID' },
+    },
+    required: ['article_id'],
+  },
+  handler: async ({ directory_id, article_id }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.get(`/directories/${dir}/articles/${article_id}`);
+    return data.data || data;
+  },
+};
+
+export const createArticle = {
+  name: 'create_article',
+  description: 'Create a new blog article. Provide either "content" (HTML) or "markdown" for the body.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      title: { type: 'string', description: 'Article title (required)' },
+      slug: { type: 'string', description: 'URL slug (auto-generated from title if not set)' },
+      content: { type: 'string', description: 'HTML content' },
+      markdown: { type: 'string', description: 'Markdown content' },
+      active: { type: 'boolean', description: 'Published status (default: true)' },
+      thumbnail_url: { type: 'string', description: 'Thumbnail image URL' },
+      categories: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Category names (strings, not IDs)',
+      },
+      seo_title: { type: 'string', description: 'SEO title' },
+      seo_description: { type: 'string', description: 'SEO meta description' },
+    },
+    required: ['title'],
+  },
+  handler: async ({ directory_id, seo_title, seo_description, ...body }) => {
+    const dir = resolveDirectory(directory_id);
+    if (seo_title || seo_description) {
+      body.seo = {};
+      if (seo_title) body.seo.title = seo_title;
+      if (seo_description) body.seo.description = seo_description;
+    }
+    const data = await api.post(`/directories/${dir}/articles`, body);
+    return data.data || data;
+  },
+};
+
+export const updateArticle = {
+  name: 'update_article',
+  description: 'Update an existing article. Only pass fields you want to change.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      article_id: { type: 'string', description: 'Article ID to update' },
+      title: { type: 'string', description: 'Article title' },
+      slug: { type: 'string', description: 'URL slug' },
+      content: { type: 'string', description: 'HTML content' },
+      markdown: { type: 'string', description: 'Markdown content' },
+      active: { type: 'boolean', description: 'Published status' },
+      thumbnail_url: { type: 'string', description: 'Thumbnail image URL' },
+      categories: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Category names',
+      },
+      seo_title: { type: 'string', description: 'SEO title' },
+      seo_description: { type: 'string', description: 'SEO meta description' },
+    },
+    required: ['article_id'],
+  },
+  handler: async ({ directory_id, article_id, seo_title, seo_description, ...body }) => {
+    const dir = resolveDirectory(directory_id);
+    if (seo_title || seo_description) {
+      body.seo = {};
+      if (seo_title) body.seo.title = seo_title;
+      if (seo_description) body.seo.description = seo_description;
+    }
+    const data = await api.put(`/directories/${dir}/articles/${article_id}`, body);
+    return data.data || data;
+  },
+};
+
+export const deleteArticle = {
+  name: 'delete_article',
+  description: 'Delete an article from a directory.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      article_id: { type: 'string', description: 'Article ID to delete' },
+    },
+    required: ['article_id'],
+  },
+  handler: async ({ directory_id, article_id }) => {
+    const dir = resolveDirectory(directory_id);
+    await api.delete(`/directories/${dir}/articles/${article_id}`);
+    return { success: true, message: `Article ${article_id} deleted.` };
+  },
+};
+
+export const toggleArticle = {
+  name: 'toggle_article',
+  description: 'Toggle an article between active and inactive status.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      directory_id: { type: 'string', description: 'Directory ID' },
+      article_id: { type: 'string', description: 'Article ID to toggle' },
+    },
+    required: ['article_id'],
+  },
+  handler: async ({ directory_id, article_id }) => {
+    const dir = resolveDirectory(directory_id);
+    const data = await api.patch(`/directories/${dir}/articles/${article_id}/toggle`);
+    return data.data || data;
+  },
+};
+
+// ─── Export all tools ───
+
+export const allTools = [
+  listDirectories,
+  listCategories,
+  getCategory,
+  createCategory,
+  updateCategory,
+  deleteCategory,
+  listTags,
+  getTag,
+  createTag,
+  updateTag,
+  deleteTag,
+  listCustomFields,
+  listListings,
+  getListing,
+  createListing,
+  updateListing,
+  deleteListing,
+  checkListingExists,
+  bulkCreateListings,
+  listArticles,
+  getArticle,
+  createArticle,
+  updateArticle,
+  deleteArticle,
+  toggleArticle,
+];