@esaio/esa-mcp-server 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build:*)",
+      "WebFetch(domain:openapi-ts.dev)",
+      "WebFetch(domain:docs.esa.io)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(rm:*)",
+      "Bash(mv:*)",
+      "Bash(npm run test:run:*)",
+      "Bash(npm run type-check:*)",
+      "Bash(npm test:*)",
+      "WebFetch(domain:modelcontextprotocol.io)",
+      "Bash(git mv:*)",
+      "Bash(git add:*)",
+      "Bash(node:*)",
+      "Bash(npm run lint:*)",
+      "Bash(git commit:*)",
+      "Bash(grep:*)"
+    ],
+    "deny": []
+  }
+}

package/.dockerignore

@@ -0,0 +1,36 @@
+.git
+.github
+
+.env
+.env.*
+.envrc
+
+.vscode
+.idea
+*.swp
+*.swo
+*~
+.DS_Store
+
+*.log
+npm-debug.log*
+
+tmp
+temp
+.tmp
+
+node_modules
+.node-version
+
+README.md
+LICENSE
+
+coverage
+
+.claude
+CLAUDE.md
+Dockerfile
+
+bin
+build
+dist

package/.envrc

@@ -0,0 +1,2 @@
+export ESA_ACCESS_TOKEN=ep2_BI_DX0c-_GB-dlNEcbVYdJqZhkA4gKQtHvmL9LLWBqo
+export ESA_API_BASE_URL=http://api.lvh.me:3000

package/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: daily
+- package-ecosystem: npm
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "03:00"
+    timezone: Asia/Tokyo
+  open-pull-requests-limit: 10
+  ignore:
+    - dependency-name: "zod"
+      update-types: ["version-update:semver-major"]
+    - dependency-name: "@types/node"
+      update-types: ["version-update:semver-major"]

package/.github/workflows/docker-publish.yml

@@ -0,0 +1,120 @@
+name: Docker Build and Push
+
+on:
+  push:
+    tags: [ 'v*' ]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - name: Prepare
+      run: |
+        platform=${{ matrix.platform }}
+        echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
+
+    - name: Checkout repository
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # https://github.com/actions/checkout/tree/v5
+
+    - name: Log in to Container Registry
+      uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # https://github.com/docker/login-action/tree/v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Extract metadata
+      id: meta
+      uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # https://github.com/docker/metadata-action/tree/v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # https://github.com/docker/setup-buildx-action/tree/v3
+
+    - name: Build and push by digest
+      id: build
+      uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # https://github.com/docker/build-push-action/tree/v6
+      with:
+        context: .
+        platforms: ${{ matrix.platform }}
+        labels: ${{ steps.meta.outputs.labels }}
+        outputs: type=image,name=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+    - name: Export digest
+      run: |
+        mkdir -p /tmp/digests
+        digest="${{ steps.build.outputs.digest }}"
+        touch "/tmp/digests/${digest#sha256:}"
+
+    - name: Upload digest
+      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # https://github.com/actions/upload-artifact/tree/v4
+      with:
+        name: digests-${{ env.PLATFORM_PAIR }}
+        path: /tmp/digests/*
+        if-no-files-found: error
+        retention-days: 1
+
+  merge:
+    runs-on: ubuntu-latest
+    needs:
+      - build
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - name: Download digests
+      uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # https://github.com/actions/download-artifact/tree/v5
+      with:
+        path: /tmp/digests
+        pattern: digests-*
+        merge-multiple: true
+
+    - name: Log in to Container Registry
+      uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # https://github.com/docker/login-action/tree/v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # https://github.com/docker/setup-buildx-action/tree/v3
+
+    - name: Extract metadata
+      id: meta
+      uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # https://github.com/docker/metadata-action/tree/v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        tags: |
+          type=semver,pattern={{version}}
+          type=semver,pattern={{major}}.{{minor}}
+          type=semver,pattern={{major}}
+
+    - name: Create manifest list and push
+      working-directory: /tmp/digests
+      run: |
+        docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+          $(printf '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@sha256:%s ' *)
+
+    - name: Inspect image
+      run: |
+        docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.meta.outputs.version }}

package/.github/workflows/main.yml

@@ -0,0 +1,41 @@
+name: CI
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+env:
+  NODE_VERSION: 20.19.4
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # https://github.com/actions/checkout/tree/v5
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # https://github.com/actions/setup-node/tree/v5
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run linting
+        run: |
+          output=$(npm run lint 2>&1)
+          echo "$output"
+          if echo "$output" | grep -q "schema version does not match"; then
+            echo "::error::Biome schema version mismatch detected. Please run 'npx biome migrate --write' to update biome.json"
+            exit 1
+          fi
+      - name: Run type checking
+        run: npm run type-check
+      - name: Run tests
+        run: npm run test:coverage
+      - name: Upload coverage reports
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # https://github.com/actions/upload-artifact/tree/v4
+        with:
+          name: coverage
+          path: coverage/
+      - name: Build
+        run: npm run build

package/.node-version

@@ -0,0 +1 @@
+24.4.1

package/CLAUDE.md

@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test              # Watch mode
+npm run test:run      # Single run
+npm run test:coverage # With coverage report
+
+# Linting
+npm run lint         # Check for linting issues
+npm run lint:fix     # Auto-fix linting and formatting issues
+
+# Type checking
+npm run type-check   # Check TypeScript types without building
+```
+
+## Architecture Overview
+
+This is an MCP (Model Context Protocol) server implementation for esa.io, using STDIO transport for communication. The architecture follows a simple structure:
+
+### Core Components
+
+1. **MCP Server Setup** (`src/index.ts`): Entry point that initializes the MCP server with STDIO transport. Handles transport lifecycle events and graceful error handling.
+
+2. **Configuration** (`src/config/index.ts`): Centralized configuration management that reads from environment variables. Required env vars:
+   - `ESA_ACCESS_TOKEN`: Required for esa.io API authentication
+   - `ESA_API_BASE_URL`: Optional API base URL (defaults to https://api.esa.io)
+
+### Key Technical Details
+
+- **Module System**: ES modules (type: "module" in package.json)
+- **TypeScript**: Strict mode enabled with comprehensive type checking
+- **Code Style**: Enforced by Biome (2 spaces, double quotes, semicolons, trailing commas)
+- **Node Version**: Requires Node.js >= 20.19.4
+
+### MCP Server Pattern
+
+The server follows the standard MCP pattern:
+1. Validate configuration on startup
+2. Create McpServer instance with name and version
+3. Initialize StdioServerTransport for STDIO communication
+4. Handle transport lifecycle (onclose, onerror)
+5. Connect server to transport
+
+When extending functionality, new tools and resources should be registered with the server instance before connecting to transport.
+
+## Testing Guidelines
+
+### Test Writing Principles
+
+When writing tests, follow these principles for maintainable and readable test code:
+
+1. **Import Order Optimization**
+   - Type imports first (`import type`)
+   - External dependencies next
+   - Internal modules last
+   - Group related imports together
+
+2. **Mock Creation Patterns**
+   - Use `as unknown as` pattern for type casting to keep mocks minimal and focused
+   - Create helper functions for complex mock objects (e.g., `createMockConfig`, `createMockServer`)
+   - Extract repetitive mock setup into shared helper functions (e.g., `setupServerMocks`)
+   - Return mock instances from helper functions for assertion access
+
+3. **Mock Documentation**
+   - Add concise comments explaining the purpose of each mock
+   - Focus on WHY the mock is needed, not WHAT it does
+   - Keep comments brief and directly above the mock definition
+
+4. **Module Mocking with vi.doMock**
+   - Use `vi.doMock` for replacing entire modules during import resolution
+   - Always call `vi.doMock` before the module import
+   - Use dynamic imports (`await import()`) after setting up module mocks
+   - Remember that `vi.doMock` is fundamentally different from `vi.fn()` - it intercepts module loading
+
+5. **Test Structure**
+   - Keep each test focused on a single behavior
+   - Use descriptive test names that explain the expected outcome
+   - Group related tests with `describe` blocks
+   - Clean up mocks in `beforeEach`/`afterEach` hooks
+
+### Example Test Pattern
+
+- READ src/__tests__/index.test.ts

package/Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+
+FROM node:alpine AS base
+
+WORKDIR /app
+
+FROM base AS deps
+
+RUN --mount=type=bind,source=package.json,target=package.json \
+    --mount=type=bind,source=package-lock.json,target=package-lock.json \
+    --mount=type=cache,target=/root/.npm \
+    npm ci --only=production
+
+FROM base AS build
+
+RUN --mount=type=bind,source=package.json,target=package.json \
+    --mount=type=bind,source=package-lock.json,target=package-lock.json \
+    --mount=type=cache,target=/root/.npm \
+    npm ci
+
+COPY . .
+
+RUN npm run build
+
+FROM base AS production
+
+ENV NODE_ENV=production
+
+USER node
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/bin ./bin
+
+ENTRYPOINT ["node", "bin/index.js"]

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2025 esa LLC
+
+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.en.md

@@ -0,0 +1,139 @@
+# esa MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[日本語](README.md) | **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
+- `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)
+
+### 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` - Prepare a post for duplication (retrieve name and body_md)
+
+### 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
+
+### 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: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.
+
+## 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

package/README.md

@@ -0,0 +1,139 @@
+# esa MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**日本語** | [English](README.en.md)
+
+esa.io の公式 MCP(Model Context Protocol)サーバー(STDIO Transport版)
+
+## 概要
+
+AI アシスタントと情報共有サービス [esa](https://esa.io) をつなぐ MCP サーバーです。Model Context Protocol 経由で、AI アシスタントから esa の記事を読んだり、作成・更新・管理などができます。
+
+## 使えるツール
+
+### チーム管理
+- `esa_get_teams` - 所属している esa チームの一覧
+- `esa_get_team_stats` - チームの統計情報（メンバー数、記事数、コメント数など）
+- `esa_get_team_tags` - チーム内で使われているタグと使用回数
+- `esa_get_team_members` - チームメンバーとその役割・プロフィール
+
+### 記事管理
+
+- `esa_search_posts` - 記事を検索
+- `esa_get_post` - 記事IDから記事を取得
+- `esa_create_post` - 新しい記事を作成（タグ、カテゴリー、WIP ステータス付き）
+- `esa_update_post` - 記事を更新（タイトル、本文、タグ、カテゴリー、WIP ステータス）
+
+### 記事の操作
+- `esa_archive_post` - 記事をアーカイブ（Archived/ カテゴリーへ移動）
+- `esa_ship_post` - 記事を Ship It!（WIP を外して公開）
+- `esa_duplicate_post` - 記事を複製するための準備（タイトルと本文を取得）
+
+### コメント管理
+- `esa_get_comment` - コメント ID からコメントを取得
+- `esa_create_comment` - 記事にコメントを追加
+- `esa_update_comment` - コメントを編集
+- `esa_delete_comment` - コメントを削除
+- `esa_get_post_comments` - 記事のコメント一覧（ページング対応）
+- `esa_get_team_comments` - チーム全体のコメント一覧（ページング対応）
+
+### カテゴリー管理
+- `esa_get_categories` - 指定パス配下のカテゴリー一覧
+- `esa_get_top_categories` - トップレベルのカテゴリー一覧
+
+### ヘルプとドキュメント
+- `esa_get_search_options_help` - esa の検索構文ヘルプ
+- `esa_get_markdown_syntax_help` - esa の Markdown 記法ヘルプ
+- `esa_search_help` - esa のドキュメントから機能や用語を検索
+
+## リソース
+
+- `esa_recent_posts` - 最近更新された記事の一覧
+  - テンプレート: `esa://teams/{teamName}/posts/recent`
+  - 戻り値: 最近更新された記事の JSON リスト
+
+## プロンプト
+
+- `esa_summarize_post` - esa の記事を要約
+  - 入力: チーム名と記事ID
+  - 出力: 記事の構造化された要約
+
+## MCP クライアントの設定
+
+MCP クライアントの設定ファイルに以下を追加します：
+
+### 用意する環境変数
+
+- ESA_ACCESS_TOKEN: アクセストークン
+   - 必要なスコープ: `read write` または `admin:comment read:post write:post read:category read:tag read:team read:member`
+   - [PAT v2](https://docs.esa.io/posts/559)を推奨します。
+- LANG: UI の言語設定
+
+### Claude Desktop の例
+
+`claude_desktop_config.json` への追加方法：
+
+#### オプション 1: docker(推奨)
+
+```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": "ja"
+      }
+    }
+  }
+}
+```
+
+#### オプション 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": "ja"
+      }
+    }
+  }
+}
+```
+
+> **注意**: `/path/to/your/node` は `which node` で調べたパスに置き換えてください。
+
+## リンク
+
+- [esa.io](https://esa.io) - 情報共有サービス esa
+- [Model Context Protocol](https://modelcontextprotocol.io) - MCP の詳細
+- [API ドキュメント](https://docs.esa.io/posts/102) - esa API リファレンス
+- [Claude Desktop](https://claude.ai/download) - MCP 対応の AI アシスタント
+
+## サポート
+
+- 📧 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