# esa MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[日本語](https://github.com/esaio/esa-mcp-server#readme) | **English**

Official Model Context Protocol (MCP) server for esa.io - STDIO transport version.

## Overview

This MCP server provides seamless integration between AI assistants and [esa.io](https://esa.io), a collaborative documentation platform. It enables AI assistants to read, create, update, and manage esa documents directly through the Model Context Protocol.

## Available Tools

### Team Management

- `esa_get_teams` - Get user's accessible esa teams
- `esa_get_team_stats` - Get team statistics (members, posts, comments, stars, watches, active users)
- `esa_get_team_tags` - Get all tags used in team posts with count
- `esa_get_team_members` - Get team members with roles and profile information

### Post Management

- `esa_search_posts` - Search for posts in esa.io
- `esa_get_post` - Get a specific post by post number (includes `backlinks_count` and `body_md_stats` with the body's character and line counts)
- `esa_get_post_backlinks` - List posts that reference a specific post with pagination
- `esa_create_post` - Create a new post with tags, category, and WIP status
- `esa_update_post` - Update existing post (title, content, tags, category, WIP status)
- `esa_append_post` - Append content to the end of a post's body (no need to fetch the current body; saved as a new revision)
- `esa_prepend_post` - Prepend content to the beginning of a post's body (no need to fetch the current body; saved as a new revision)

### Post Actions

- `esa_archive_post` - Archive a post by moving to Archived/ category
- `esa_ship_post` - Ship a post (mark as complete by setting wip to false)
- `esa_duplicate_post` - Duplicate a post (create a new WIP post with the same title and body; cross-team duplication is also supported)

### Comment Management

- `esa_get_comment` - Get a specific comment by ID
- `esa_create_comment` - Create a new comment on a post
- `esa_update_comment` - Update an existing comment
- `esa_delete_comment` - Delete a comment
- `esa_get_post_comments` - Get comments for a specific post with pagination
- `esa_get_team_comments` - Get team comments with pagination

### Category Management

- `esa_get_categories` - Get categories and subcategories for a specific path
- `esa_get_top_categories` - Get all top-level categories for a team
- `esa_get_all_category_paths` - Get all category paths in a team (with post counts, supports filtering)
  - Perfect for understanding category structure, organization planning, and cleanup
  - Filter examples: `prefix: "dev"` for development-related, `match: "api"` for API-related categories

### Attachments

- `esa_get_attachment` - Retrieve an attachment file from esa posts and comments
  - Returns base64-encoded data for supported images (JPEG, PNG, GIF, WebP) under 30MB
  - Returns signed URLs (valid for 5 minutes) for other file types, larger images, or when forceSignedUrl is specified

### Help & Documentation

- `esa_get_search_options_help` - Get esa search syntax documentation
- `esa_get_markdown_syntax_help` - Get esa Markdown syntax documentation
- `esa_search_help` - Search esa documentation for features and terminology

## Available Resources

- `esa_recent_posts` - Fetch recent updated posts from esa team
  - Template: `esa://teams/{teamName}/posts/recent`
  - Returns: JSON list of recently updated posts

## Available Prompts

- `esa_summarize_post` - Summarize an esa post content
  - Input: Team name and post number
  - Output: Structured summary of the post content

## MCP Client Configuration

Add to your MCP client configuration file:

### Required Environment Variables

- ESA_ACCESS_TOKEN: Access Token
  - Required scopes: `read write` or `admin:comment read:post write:post read:category read:tag read:attachment read:team read:member`
  - [PAT v2](https://docs.esa.io/posts/559) is recommended.
- LANG: Language for UI

### Claude Desktop Example

Add to `claude_desktop_config.json`:

#### Option 1: Docker (Recommended)

```json
{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_ACCESS_TOKEN",
        "-e",
        "LANG",
        "ghcr.io/esaio/esa-mcp-server"
      ],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "en"
      }
    }
  }
}
```

#### Option 2: npx

```json
{
  "mcpServers": {
    "esa": {
      "command": "/Users/your-username/.nodenv/shims/npx",
      "args": ["@esaio/esa-mcp-server"],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "en"
      }
    }
  }
}
```

> **Note**: Replace `/path/to/your/node` with the output of `which node` command.

## Registry

This package ships `registry.json` at the package root, exposing registered tools, resources, and prompts. It can be consumed programmatically without spawning the server:

```js
import registry from "@esaio/esa-mcp-server/registry.json" with { type: "json" };
```

Schema:

```json
{
  "tools": [{ "name": "esa_get_teams" }, "..."],
  "resources": [
    { "name": "esa_recent_posts", "uriTemplate": "esa://teams/{teamName}/posts/recent" }
  ],
  "prompts": [{ "name": "esa_summarize_post" }]
}
```

The file is regenerated by `npm run build:registry` and a CI check enforces that it stays in sync with the registered set.

## Links

- [esa.io](https://esa.io) - The collaborative documentation platform
- [Model Context Protocol](https://modelcontextprotocol.io) - Learn more about MCP
- [API Documentation](https://docs.esa.io/posts/102) - esa.io API reference
- [Claude Desktop](https://claude.ai/download) - AI assistant with MCP support

## Support

- 📧 Support: [Feedback Form](https://esa.io/feedbacks/new)
- 🐛 Issues: [GitHub Issues](https://github.com/esaio/esa-mcp-server/issues)
- 📖 Help: [esa Docs](https://docs.esa.io)

---

Made with ❤️ by the esa team