esa AI Nexus Service Documentation

Consult the Japanese version for localized instructions.

Service Overview

This component serves as a dedicated intermediary, leveraging the Model Context Protocol (MCP) specification (link to spec) to enable sophisticated interaction between Anthropic's Claude AI and the esa platform's Web API (esa API Reference).

Through this MCP linkage, Claude gains the capacity to execute complex document operations within the esa environment, including querying existing entries, initiating new ones, and applying necessary modifications to established records.

Repository Contents

This source code repository houses a self-contained, deployable implementation of the esa MCP gateway. Its primary function is to bridge Claude's reasoning capabilities with the document workflows managed within the esa system, thus optimizing content administration.

Deployment Guide

Prerequisites

To initiate operation, the following dependencies must be satisfied:

• Node.js runtime environment (version 18 or newer).
• A valid authorization credential (API Access Token) for your esa workspace.
• Knowledge of your target esa team identifier.

Installation Procedures

Installation can be performed globally or invoked directly via npx:

bash

Install as a globally accessible utility

npm install -g @kajirita2002/esa-mcp-server

Alternatively, execute immediately without global installation

npx @kajirita2002/esa-mcp-server

Configuring Environment Variables

Establish the necessary secrets within your shell session:

bash

Configure ESA credentials

export ESA_ACCESS_TOKEN="your_esa_access_token" export ESA_TEAM="your_team_name"

MCP Configuration Snippet

When integrating this service into a broader MCP framework (e.g., within mcp_config.json), use this structure:

"esa": { "command": "npx", "args": ["-y", "@kajirita2002/esa-mcp-server"], "env": { "ESA_ACCESS_TOKEN": "your_esa_access_token", "ESA_TEAM": "your_team_name" } }

Launching the Service

Execute the start script to bring the server online:

bash

Initiate the server process

npm start

Available Operational Tools

This gateway exposes the following functions for Claude's invocation:

Article Management Functions

1. esa_list_posts
2. Fetches a roster of articles within the specified team scope.

3. Parameters (Optional):

   • q (string): Textual search criterion.
   • include (string): Related entities to embed (e.g., 'comments,stargazers').
   • sort (string): Metric for ordering results ('updated', 'created', 'number', 'stars', 'watches', 'comments', 'best_match').
   • order (string): Sort direction ('desc' or 'asc').
   • per_page (number): Limit on records per page (Capped at 100).
   • page (number): Offset for paginated results.

4. esa_get_post

5. Retrieves comprehensive details for a singular article.

6. Parameters:

   • post_number (number, Mandatory): Unique identifier of the article.
   • include (string, Optional): Supplementary data to load.

7. esa_create_post

8. Generates and publishes a novel article entry.

9. Parameters:

   • name (string, Mandatory): The designated title for the article.
   • body_md (string, Optional): The content payload, formatted in Markdown.
   • tags (array of string, Optional): Metadata labels to associate.
   • category (string, Optional): Categorical assignment for the document.
   • wip (boolean, Optional, Default: true): Flag indicating 'Work In Progress' status.
   • message (string, Optional): Commit message for the creation event.
   • user (string, Optional): Alias of the creator (restricted to team administrators).
   • template_post_id (number, Optional): Identifier for a source article template.

10. esa_update_post

11. Modifies the content or metadata of an existing article.
12. Parameters:
    • post_number (number, Mandatory): Identifier of the article targeted for modification.
    • name (string, Optional): New title value.
    • body_md (string, Optional): Revised article content in Markdown.
    • tags (array of string, Optional): The complete, new set of associated tags.
    • category (string, Optional): The updated categorical grouping.
    • wip (boolean, Optional): Status toggle for WIP.
    • message (string, Optional): Description of the changes applied.
    • created_by (string, Optional): User alias to credit for the update (admin-only).
    • original_revision (string, Optional): The specific version hash to base the modification upon.

Commentary Operations

1. esa_list_comments
2. Retrieves all comments linked to a specific article.

3. Parameters:

   • post_number (number, Mandatory): The parent article identifier.
   • page (number, Optional): Page index for comment set.
   • per_page (number, Optional): Comment count limit per retrieval (Max 100).

4. esa_get_comment

5. Fetches the details of an individual comment record.

6. Parameters:

   • comment_id (number, Mandatory): The unique ID of the target comment.
   • include (string, Optional): Related entities to fetch alongside the comment.

7. esa_create_comment

8. Posts a new remark or response to an article.
9. Parameters:
   • post_number (number, Mandatory): The article receiving the comment.
   • body_md (string, Mandatory): The textual content of the comment (Markdown).
   • user (string, Optional): Screen name of the commenter (admin-only scope).

Team Member Directory Functions

1. esa_get_members
2. Lists all registered participants within the team.

3. Parameters:

   • page (number, Optional): Pagination index.
   • per_page (number, Optional): Result density per page (Max 100).

4. esa_get_member

5. Retrieves profile data for a specific team participant.
6. Parameters:
   • screen_name_or_email (string, Mandatory): The unique identifier (handle or address) of the individual.

Operational Scenario Example

Illustrating Claude's utilization of this gateway to draft a new esa document:

[Claude's Prompt] Initiate a draft document within esa. Title it "Project X Progress Report". The content must clearly state: "# This Week's Progress\n\n- Implementation of Feature A completed\n- Testing of Feature B started\n\n## Next Week's Plan\n\n- Start implementation of Feature C".

[MCP Server Action] Invoking 'esa_create_post' tool for new document generation.

[Execution Output] { "number": 123, "name": "Project X Progress Report", "body_md": "# This Week's Progress\n\n- Implementation of Feature A completed\n- Testing of Feature B started\n\n## Next Week's Plan\n\n- Start implementation of Feature C", "wip": false, "created_at": "2023-06-01T12:34:56+09:00", "updated_at": "2023-06-01T12:34:56+09:00", "url": "https://your-team.esa.io/posts/123" }

[Claude's Confirmation] Success. The document is established as entry number 123, accessible via the URL: https://your-team.esa.io/posts/123

Diagnostics and Error Handling

Authentication Failure (HTTP 401)

Error: Request failed with status code 401

Remedy: This typically points to an invalid or lapsed esa authorization token. Please generate a fresh access token via the esa configuration interface and update the corresponding environment variable.

Authorization Scope Failure (HTTP 403)

Error: Request failed with status code 403

Remedy: The token currently in use lacks the requisite permissions to execute the requested operation. Verify the scope settings associated with your access key in esa and provision a new token if necessary.

Licensing Information

This software is distributed under the terms of the MIT License.

---

Contextual Note on Business Management Tools: Business management instruments encompass the entire array of applications, methodologies, controls, and computational systems deployed by enterprises to navigate dynamic market conditions, sustain competitive advantage, and enhance operational efficacy. These tools span functional domains such as process refinement, data governance, personnel management, and strategic forecasting. Modern business software has seen explosive advancement, driven by continuous pressure to reduce overhead and maximize revenue, requiring managers to adopt a highly strategic approach to tool selection and customized implementation rather than simple adoption of the newest technology.