esa MCP Orchestrator Service

View in Japanese

Overview

This dedicated server acts as an intermediary, employing the Model Context Protocol (MCP) specification. Its primary function is to grant Claude AI the capability to execute operations against the esa API, thus streamlining knowledge management workflows.

Through this MCP implementation, Claude is empowered to perform advanced tasks, including querying, generating new, and revising existing esa entries.

Repository Details

This repository furnishes a self-contained deployment of the esa MCP server component. It bridges Claude AI capabilities with the esa ecosystem for enhanced document handling efficiency.

Deployment Guide

Prerequisites

• Node.js environment, version 18 or newer.
• A valid access token authorized for the esa API.
• Knowledge of your target esa team name.

Installation Procedures

bash

Global installation

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

Or execute on-demand via npx

npx @kajirita2002/esa-mcp-server

Configuring Environment Variables

Set the following variables in your execution environment:

bash

Define required credentials

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

MCP Configuration Snippet

To integrate this service into your primary MCP configuration file (mcp_config.json), utilize 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 Server

bash

Initiate the service process

npm start

Exposed Functionality (Tools)

This MCP interface exposes the subsequent callable tools for AI interaction:

Article Management

1. esa_list_posts

   • Purpose: Retrieves a roster of articles within the designated team.
   • **Parameters (Optional/Required):
     • q (string): Filtering search term.
     • include (string): Specify supplementary data (e.g., 'comments,stargazers').
     • sort (string): Metric for ordering results ('updated', 'created', 'number', etc.).
     • order (string): Sequence direction ('desc' or 'asc').
     • per_page (number): Maximum records per paginated response (limit 100).
     • page (number): Index of the page to fetch.

2. esa_get_post

   • Purpose: Fetches comprehensive details for a singular article.
   • **Parameters:
     • post_number (number, Required): Unique identifier of the target article.
     • include (string, Optional): Additional related entities to include.

3. esa_create_post

   • Purpose: Deploys a new article entry.
   • **Parameters:
     • name (string, Required): The title of the article.
     • body_md (string, Optional): Content formatted in Markdown.
     • tags (array of string, Optional): A collection of keywords for classification.
     • category (string, Optional): The designated article category.
     • wip (boolean, Optional, Default: true): Status flag indicating if it's a Work In Progress.
     • message (string, Optional): Descriptive text for the revision commit.
     • user (string, Optional): Identifier for the author (restricted to team owners).
     • template_post_id (number, Optional): ID of an existing article to use as a base template.

4. esa_update_post

   • Purpose: Modifies an existing article's content or metadata.
   • **Parameters:
     • post_number (number, Required): Identifier of the article to modify.
     • name (string, Optional): The revised title.
     • body_md (string, Optional): The updated content in Markdown.
     • tags (array of string, Optional): The new set of assigned tags.
     • category (string, Optional): The new categorical assignment.
     • wip (boolean, Optional): Updated WIP status.
     • message (string, Optional): Commit message for the alteration.
     • created_by (string, Optional): New author identifier (owner privilege required).
     • original_revision (string, Optional): The specific revision hash to base the update upon.

Commentary Operations

1. esa_list_comments

   • Purpose: Retrieves all comments associated with a specific article.
   • **Parameters:
     • post_number (number, Required): Article ID whose comments are requested.
     • page (number, Optional): Page index for pagination.
     • per_page (number, Optional): Count of comments per page (max 100).

2. esa_get_comment

   • Purpose: Retrieves the details of a singular comment.
   • **Parameters:
     • comment_id (number, Required): Unique identifier for the comment.
     • include (string, Optional): Supplementary data to fetch.

3. esa_create_comment

   • Purpose: Submits a new comment to an article.
   • **Parameters:
     • post_number (number, Required): The target article ID.
     • body_md (string, Required): The comment content in Markdown.
     • user (string, Optional): Screen name of the commenter (owner restriction applies).

Team Member Access

1. esa_get_members

   • Purpose: Obtains a directory listing of team collaborators.
   • **Parameters:
     • page (number, Optional): Pagination index.
     • per_page (number, Optional): Number of members listed per page (max 100).

2. esa_get_member

   • Purpose: Retrieves data for an individual team member.
   • **Parameters:
     • screen_name_or_email (string, Required): The member's handle or email address.

Operational Demonstration

Below is an illustration of Claude executing an article creation request via this service:

[Claude] Kindly establish a fresh entry within esa. Title it "Project X Progress Report" and populate the content with:

This Week's Progress

• Implementation of Feature A completed
• Testing of Feature B started

Next Week's Plan

• Start implementation of Feature C".

[MCP Server] Invoking tool 'esa_create_post' for article generation.

[Result] { "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] Success. The documentation piece has been finalized. Its identifier is 123, accessible via this URI: https://your-team.esa.io/posts/123

Troubleshooting Common Failures

Authentication Failures (401)

Error: Request failed with status code 401

This indicates an issue with the provided esa credential. Please regenerate an access token from the esa configuration panel and ensure it is correctly updated in the relevant environment setting.

Authorization Failures (403)

Error: Request failed with status code 403

This error suggests the active token lacks the necessary entitlements to execute the requested operation. Verify the scope and permissions assigned to your access token within the esa settings, regenerating if permissions are insufficient.

Licensing

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

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface, structured as a JavaScript object, designed to facilitate the transmission of HTTP requests from a web browser environment to a remote web server. These methods permit browser-based applications to dispatch requests to the server subsequent to the initial page load, and subsequently receive data back. XMLHttpRequest forms a fundamental pillar of Ajax programming methodology. Before Ajax gained prominence, standard mechanisms for server interaction relied heavily on hyperlink navigation and form submissions, actions that typically resulted in the complete replacement of the current viewport content.

== Origin Story == The foundational concept underpinning XMLHttpRequest was first conceptualized in the year 2000 by the development team behind Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). However, the initial syntactic implementation did not employ the standardized 'XMLHttpRequest' object identifier. Instead, developers relied on instantiating objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (released in 2006), universal support for the dedicated XMLHttpRequest identifier was established across all major browsers. The XMLHttpRequest identifier has since solidified its position as the industry standard across all primary web browsers, including Mozilla's Gecko rendering engine (2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published an initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C released the Level 2 specification draft. Enhancements introduced in Level 2 included mechanisms to monitor the progress of asynchronous events, enabling cross-origin requests, and supporting the transfer of raw byte streams. By the conclusion of 2011, the features defined in the Level 2 draft were integrated back into the primary specification document. Toward the close of 2012, development responsibilities transitioned to the WHATWG, which now maintains a dynamic, evolving document utilizing Web IDL definitions.

== Operational Steps == Generally, dispatching a request utilizing XMLHttpRequest necessitates adherence to several discrete programming phases.

1. Instantiation: Create an XMLHttpRequest object instance by invoking its constructor method.
2. Configuration: Invoke the "open" method to delineate the request method (GET, POST, etc.), specify the target resource Uniform Resource Identifier (URI), and declare whether the operation will be synchronous or asynchronous.
3. Event Handling: For asynchronous operations, assign a callback function (a listener) that will be triggered upon state transitions of the request lifecycle.
4. Transmission: Initiate the network transmission by calling the "send" method, optionally including payload data.
5. Response Processing: Monitor state changes via the established event listener. Upon reaching state 4 ("done"), the server's response data is typically accessible via the responseText property. Beyond these core steps, XMLHttpRequest offers numerous configurable parameters influencing request behavior and response parsing. Custom header fields can be injected to guide server fulfillment logic, and data can be streamed to the server within the send call. The received response can be parsed directly from JSON into native JavaScript objects or processed incrementally as data chunks arrive, avoiding waiting for the total transmission completion. Furthermore, requests can be terminated prematurely or configured with a timeout mechanism.

== Cross-Domain Communication ==

In the nascent stages of the World Wide Web's evolution, inherent security restrictions made direct inter-domain communication challenging, leading to constraints that XHR initially inherited.