@esaio/esa-mcp-server 0.1.0

package/bin/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import{McpServer as e,ResourceTemplate as t}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as n}from"@modelcontextprotocol/sdk/server/stdio.js";import r from"i18next";import i from"openapi-fetch";import{z as a}from"zod";var o={name:`@esaio/esa-mcp-server`,version:`0.1.0`,description:`Official MCP server for esa.io - STDIO transport version`,main:`bin/index.js`,type:`module`,bin:{"esa-mcp-server":`./bin/index.js`},scripts:{build:`tsdown`,test:`vitest`,"test:run":`vitest run`,"test:coverage":`vitest run --coverage`,lint:`biome check . --error-on-warnings`,"lint:fix":`biome check --write .`,"type-check":`tsc --noEmit`},keywords:[`mcp`,`model-context-protocol`,`esa`,`esa.io`,`documentation`,`knowledge-base`],author:`esa LLC`,license:`MIT`,dependencies:{"@modelcontextprotocol/sdk":`^1.17.5`,axios:`^1.11.0`,i18next:`^25.5.2`,"openapi-fetch":`^0.14.0`,zod:`^3.23.8`},devDependencies:{"@biomejs/biome":`^2.2.4`,"@types/node":`^20.19.13`,"@vitest/coverage-v8":`^3.2.4`,"openapi-typescript":`^7.9.1`,tsdown:`^0.15.0`,tsx:`^4.20.5`,typescript:`^5.9.2`,vitest:`^3.2.4`},engines:{node:`>=20.19.4`}};const s={esa:{apiAccessToken:process.env.ESA_ACCESS_TOKEN||``,apiBaseUrl:process.env.ESA_API_BASE_URL||`https://api.esa.io`},server:{name:`esa-mcp-server`,version:o.version,description:`Official MCP server for esa.io`}};function c(){if(!s.esa.apiAccessToken)throw Error(`ESA_ACCESS_TOKEN environment variable is required`)}var ee={prompts:{summarize_post:{title:`Summarize esa post`,description:`Summarize an esa post in various formats (bullet points, paragraph, or keywords)`,args:{team_name:`The name of the esa team`,post_number:`The post number to summarize`,format:`Summary format (bullet/paragraph/keywords)`}}}},te={prompts:{summarize_post:{title:`esaの記事の要約`,description:`esa記事を指定した形式で要約します(bullet: 箇条書き, paragraph: 文章, keywords: キーワード)`,args:{team_name:`esaチーム名`,post_number:`要約する記事番号`,format:`要約形式 (bullet/paragraph/keywords)`}}}};async function ne(){let e=process.env.LC_ALL?.split(/[-_.]/)[0]||process.env.LC_MESSAGES?.split(/[-_.]/)[0]||process.env.LANG?.split(/[-_.]/)[0]||process.env.LANGUAGE?.split(/[-_.]/)[0]||`en`;return await r.init({lng:e,fallbackLng:`en`,resources:{ja:{translation:te},en:{translation:ee}},interpolation:{escapeValue:!1}}),r}function l(e,t){return r.t(e,t)}function re(e){return{async onRequest({request:t}){return t.headers.set(`Authorization`,`Bearer ${e}`),t},async onResponse({response:e}){let t=e.headers.get(`x-ratelimit-limit`),n=e.headers.get(`x-ratelimit-remaining`);return t&&n&&console.error(`Rate limit: ${n}/${t}`),e},async onError({error:e}){console.error(`Network Error:`,e)}}}const ie=o.version;function u(e){return{async onRequest({request:t}){return t.headers.set(`User-Agent`,`esa-mcp-server/${e} (official)`),t}}}function d(e,t=`https://api.esa.io`){let n=i({baseUrl:t});return n.use(u(ie)),n.use(re(e)),n}async function f(e,t,...n){let r;if(`apiAccessToken`in e&&`apiBaseUrl`in e)r=d(e.apiAccessToken,e.apiBaseUrl);else throw Error(`Unsupported context type. Only StdioContext is currently supported.`);return t(r,...n)}var p=class extends Error{constructor(){super(`Missing required parameter 'teamName'. Use esa_get_teams to list available teams, then retry with teamName specified.`),this.name=`MissingTeamNameError`}};function m(e){return e instanceof Error?`Error: ${e.message}`:typeof e==`number`&&e!==null?`Error: API Response(status: ${e})`:typeof e==`object`&&e?`Error: ${JSON.stringify(e,null,2)}`:`Error: ${String(e)}`}function h(e){return{content:[{type:`text`,text:JSON.stringify(e,null,2)}]}}function g(e,t){return{contents:[{uri:t,mimeType:`application/json`,text:JSON.stringify(e,null,2)}]}}function _(e){return{messages:[{role:`user`,content:{type:`text`,text:e}}]}}function v(e){return{content:[{type:`text`,text:m(e)}]}}function y(e,t){return{contents:[{uri:t,mimeType:`application/json`,text:m(e)}]}}function b(e){return{messages:[{role:`user`,content:{type:`text`,text:m(e)}}]}}const x=()=>a.object({teamName:a.string().describe(l(`prompts.summarize_post.args.team_name`)),postNumber:a.string().describe(l(`prompts.summarize_post.args.post_number`)),format:a.enum([`bullet`,`paragraph`,`keywords`]).optional().describe(l(`prompts.summarize_post.args.format`))});async function ae(e,t){let{teamName:n,postNumber:r,format:i=`bullet`}=t;if(!n)throw new p;let a=Number.parseInt(r,10);if(Number.isNaN(a)||a<=0)return b(`Post number must be a positive integer`);try{let{data:t,error:r,response:o}=await e.GET(`/v1/teams/{team_name}/posts/{post_number}`,{params:{path:{team_name:n,post_number:a}}});if(r||!o.ok)return b(r||o.status);let s=t,c=`Please summarize the following post:
+
+`;switch(c+=`Title: ${s.name}\n`,c+=`URL: ${s.url}\n`,c+=`Author: ${s.created_by.name}\n`,c+=`Created: ${s.created_at}\n`,c+=`Updated: ${s.updated_at}\n`,s.category&&(c+=`Category: ${s.category}\n`),s.tags&&s.tags.length>0&&(c+=`Tags: ${s.tags.join(`, `)}\n`),c+=`
+---
+
+`,s.body_md&&(c+=`Content:\n${s.body_md}\n\n---\n\n`),i){case`bullet`:c+=`Please provide a summary in bullet points (3-5 main points).`;break;case`paragraph`:c+=`Please provide a summary in 2-3 paragraphs.`;break;case`keywords`:c+=`Please extract and list 10-15 important keywords from this post.`;break}return _(c)}catch(e){return b(e)}}function oe(e,t){console.error(`Setting up MCP prompts...`),e.registerPrompt(`esa_summarize_post`,{title:l(`prompts.summarize_post.title`),description:l(`prompts.summarize_post.description`),argsSchema:x().shape},async e=>f(t,ae,e))}function S(e,t={}){let{truncateBody:n}=t,r=e.body_md;return n&&r&&r.length>n&&(r=`${r.slice(0,n)}...`),{url:e.url,wip:e.wip?`WIP`:`Shipped`,kind:e.kind,category_and_title_and_tags:e.full_name,body_md:r,created_at:e.created_at,updated_at:e.updated_at,created_by:e.created_by,updated_by:e.updated_by,stats:{tasks_count:e.tasks_count,done_tasks_count:e.done_tasks_count,comments_count:e.comments_count,stargazers_count:e.stargazers_count,watchers_count:e.watchers_count}}}const se={sort:`updated`,order:`desc`};async function ce(e,t){let{teamName:n,uri:r}=t;try{let{data:t,error:i,response:a}=await e.GET(`/v1/teams/{team_name}/posts`,{params:{path:{team_name:n},query:se}});if(i||!a.ok)return y(i||a.status,r);let o={...t,posts:t.posts?.map(e=>S(e,{truncateBody:500}))};return g(o,r)}catch(e){return y(e,r)}}function C(e){let t=e.indexOf(`.`);return t>=0?e.substring(0,t):e}const w=a.string().default(``).describe(`Team name (required). Use esa_get_teams first to see available teams.`).transform(C);function T(e){return a.object({teamName:w,...e})}const E=a.object({page:a.number().optional().describe(`Page number (starts from 1)`),perPage:a.number().optional().describe(`Number of items per page`),role:a.enum([`member`,`owner`]).optional().describe(`Filter by role`)});async function D(e,t={}){try{let{data:n,error:r,response:i}=await e.GET(`/v1/teams`,{params:{query:{page:t.page,per_page:t.perPage,role:t.role}}});if(r||!i.ok)return v(r||i.status);let a={...n,teams:n.teams?.map(e=>({url:e.url,name:e.name,description:e.description}))};return h(a)}catch(e){return v(e)}}const O=T({});async function k(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/stats`,{params:{path:{team_name:t.teamName}}});return r||!i.ok?v(r||i.status):h(n)}catch(e){return v(e)}}const A=T({page:a.number().optional().describe(`Page number (starts from 1)`),perPage:a.number().optional().describe(`Number of items per page`)});async function j(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/tags`,{params:{path:{team_name:t.teamName},query:{page:t.page,per_page:t.perPage}}});return r||!i.ok?v(r||i.status):h(n)}catch(e){return v(e)}}const M=T({page:a.number().optional().describe(`Page number (starts from 1)`),perPage:a.number().optional().describe(`Number of items per page`),sort:a.enum([`posts_count`,`joined`,`last_accessed`]).optional().describe(`Sort criteria`),order:a.enum([`desc`,`asc`]).optional().describe(`Sort order`)});async function N(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/members`,{params:{path:{team_name:t.teamName},query:{page:t.page,per_page:t.perPage,sort:t.sort,order:t.order}}});return r||!i.ok?v(r||i.status):h(n)}catch(e){return v(e)}}async function P(e){try{let t=await f(e,D,{});return JSON.parse(t.content[0].text).teams?.map(e=>({uri:`esa://teams/${e.name}/posts/recent`,name:`Recent posts from ${e.name}`,description:`Recent posts from ${e.name}${e.description?` (${e.description})`:``}`,mimeType:`application/json`}))||[]}catch(e){return console.error(`Failed to list teams:`,e),[]}}function F(e,n){console.error(`Setting up MCP resources...`),e.registerResource(`esa_recent_posts`,new t(`esa://teams/{teamName}/posts/recent`,{list:async()=>({resources:await P(n)})}),{title:`Recent Posts`,description:`Fetch recent updated posts from esa team`,mimeType:`application/json`},async(e,t)=>f(n,ce,{...t,uri:e.href}))}function I(e){return{full_name:e.full_name,count:e.count,has_child:e.has_child||!1}}function L(e){return{current_category:e.current_category,categories:e.categories?.map(I)||[],parent_categories:e.parent_categories?.map(e=>({current_category:e.current_category,categories:e.categories?.map(I)||[]})),readme:e.readme,no_category:e.no_category?I(e.no_category):void 0,descendant_posts:e.descendant_posts,posts:e.posts,total_count:e.total_count,per_page:e.per_page,page:e.page,prev_page:e.prev_page,next_page:e.next_page,max_per_page:e.max_per_page}}const R=T({select:a.string().describe(`Category path to retrieve`),include:a.enum([`posts`,`parent_categories`]).optional().describe(`Additional information to include`),descendantPosts:a.boolean().optional().describe(`Include descendant posts (only effective with include=posts)`),page:a.number().optional().describe(`Page number (starts from 1)`),perPage:a.number().optional().describe(`Number of items per page`)});async function z(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/categories`,{params:{path:{team_name:t.teamName},query:{select:t.select,include:t.include,descendant_posts:t.descendantPosts,page:t.page,per_page:t.perPage}}});if(r||!i.ok)return v(r||i.status);let a=L(n);return h(a)}catch(e){return v(e)}}const B=T({});async function V(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/categories/top`,{params:{path:{team_name:t.teamName}}});if(r||!i.ok)return v(r||i.status);let a=L(n);return h(a)}catch(e){return v(e)}}function H(e,t={}){let{truncateBody:n}=t,r=e.body_md;return n&&r&&r.length>n&&(r=`${r.slice(0,n)}...`),{id:e.id,post_number:e.post_number,url:e.url,body_md:r,created_at:e.created_at,updated_at:e.updated_at,created_by:e.created_by,stats:{stargazers_count:e.stargazers_count,star:e.star},stargazers:e.stargazers}}const U=T({commentId:a.number().describe(`The comment ID to retrieve`),include:a.enum([`stargazers`]).optional().describe(`Specify 'stargazers' to include stargazers in the response`)});async function W(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/comments/{comment_id}`,{params:{path:{team_name:t.teamName,comment_id:t.commentId},query:{include:t.include}}});if(r||!i.ok)return v(r||i.status);let a=H(n);return h(a)}catch(e){return v(e)}}const G=T({postNumber:a.number().describe(`The post number to comment on`),bodyMd:a.string().describe(`The comment content in Markdown format`),user:a.string().optional().describe(`Comment author's screen_name (owner permission required)`)});async function K(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.POST(`/v1/teams/{team_name}/posts/{post_number}/comments`,{params:{path:{team_name:t.teamName,post_number:t.postNumber}},body:{comment:{body_md:t.bodyMd,user:t.user}}});if(r||!i.ok)return v(r||i.status);let a=H(n,{truncateBody:300});return h(a)}catch(e){return v(e)}}const le=T({commentId:a.number().describe(`The comment ID to update`),bodyMd:a.string().describe(`The updated comment content in Markdown format`),user:a.string().optional().describe(`Comment author's screen_name (owner permission required)`)});async function ue(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.PATCH(`/v1/teams/{team_name}/comments/{comment_id}`,{params:{path:{team_name:t.teamName,comment_id:t.commentId}},body:{comment:{body_md:t.bodyMd,user:t.user}}});if(r||!i.ok)return v(r||i.status);let a=H(n);return h(a)}catch(e){return v(e)}}const de=T({commentId:a.number().describe(`The comment ID to delete`)});async function fe(e,t){try{if(!t.teamName)throw new p;let{error:n,response:r}=await e.DELETE(`/v1/teams/{team_name}/comments/{comment_id}`,{params:{path:{team_name:t.teamName,comment_id:t.commentId}}});return n||!r.ok?v(n||r.status):h({success:!0,message:`Comment deleted successfully`})}catch(e){return v(e)}}const pe=T({postNumber:a.number().describe(`The post number to get comments for`),page:a.number().optional().describe(`Page number (starts from 1)`),perPage:a.number().optional().describe(`Number of items per page`)});async function me(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/posts/{post_number}/comments`,{params:{path:{team_name:t.teamName,post_number:t.postNumber},query:{page:t.page,per_page:t.perPage}}});if(r||!i.ok)return v(r||i.status);let a=n.comments.map(e=>H(e,{truncateBody:300}));return h({...n,comments:a})}catch(e){return v(e)}}const he=T({page:a.number().optional().describe(`Page number (starts from 1)`),perPage:a.number().optional().describe(`Number of items per page`)});async function ge(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/comments`,{params:{path:{team_name:t.teamName},query:{page:t.page,per_page:t.perPage}}});if(r||!i.ok)return v(r||i.status);let a=n.comments.map(e=>H(e,{truncateBody:300}));return h({...n,comments:a})}catch(e){return v(e)}}function q(e,t){if(!e||t!==void 0)return{name:e,category:t};if(e.includes(`/`)){let t=e.split(`/`),n=t.pop(),r=t.join(`/`);return{name:n||void 0,category:r}}return{name:e,category:t}}const _e=T({postNumber:a.number().describe(`The post number to retrieve`),include:a.enum([`comments`]).optional().describe(`Specify 'comments' to include comments in the response`)});async function J(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/posts/{post_number}`,{params:{path:{team_name:t.teamName,post_number:t.postNumber},query:{include:t.include}}});if(r||!i.ok)return v(r||i.status);let a=S(n);return h(a)}catch(e){return v(e)}}const ve=T({name:a.string().describe(`The post name (title)`),bodyMd:a.string().optional().describe(`The post content in Markdown format`),tags:a.array(a.string()).optional().describe(`Tags for the post`),category:a.string().optional().describe(`Category path (e.g., 'dev/docs')`),wip:a.boolean().default(!0).describe(`Whether the post is Work In Progress. Set to false to ship it (mark as complete and ready to be published)`),message:a.string().optional().describe(`Update message for the post`)});async function Y(e,t){try{if(!t.teamName)throw new p;let{name:n,category:r}=q(t.name,t.category),{data:i,error:a,response:o}=await e.POST(`/v1/teams/{team_name}/posts`,{params:{path:{team_name:t.teamName}},body:{post:{name:n,body_md:t.bodyMd,tags:t.tags,category:r,wip:t.wip,message:t.message}}});if(a||!o.ok)return v(a||o.status);let s=S(i);return h(s)}catch(e){return v(e)}}const ye=T({postNumber:a.number().describe(`The post number to update`),name:a.string().optional().describe(`The post name (title)`),bodyMd:a.string().optional().describe(`The post content in Markdown format`),tags:a.array(a.string()).optional().describe(`Tags for the post`),category:a.string().optional().describe(`Category path (e.g., 'dev/docs')`),wip:a.boolean().optional().describe(`Whether the post is Work In Progress. Set to false to ship it (mark as complete and ready to be published)`),message:a.string().optional().describe(`Update message for the post`),originalRevision:a.object({bodyMd:a.string(),number:a.number(),user:a.string()}).optional().describe(`Original revision to check for conflicts`)});async function X(e,t){try{if(!t.teamName)throw new p;let{name:n,category:r}=q(t.name,t.category),{data:i,error:a,response:o}=await e.PATCH(`/v1/teams/{team_name}/posts/{post_number}`,{params:{path:{team_name:t.teamName,post_number:t.postNumber}},body:{post:{name:n,body_md:t.bodyMd,tags:t.tags,category:r,wip:t.wip,message:t.message,original_revision:t.originalRevision?{body_md:t.originalRevision.bodyMd,number:t.originalRevision.number,user:t.originalRevision.user}:void 0}}});if(a||!o.ok)return v(a||o.status);let s=S(i);return h(s)}catch(e){return v(e)}}function be(e){let t=e;return t===`*`&&(t=``),t=t.replace(/\bafter:(\d{4}-\d{2}-\d{2})\b/gi,`created:>$1`),t=t.replace(/\bbefore:(\d{4}-\d{2}-\d{2})\b/gi,`created:<$1`),t=t.replace(/\bsince:(\d{4}-\d{2}-\d{2})\b/gi,`created:>$1`),t=t.replace(/\buntil:(\d{4}-\d{2}-\d{2})\b/gi,`created:<$1`),t}const Z=T({query:a.string().describe(`Search query string. Use specific terms, not wildcards like "*". Empty string returns all posts.
+## Important Note for Date Queries:
+**WARNING: Do NOT use 'after:', 'before:', 'since:', or 'until:' syntax (these are from GitHub/Gmail/pplog).
+Use esa-specific date syntax: created:>YYYY-MM-DD, created:<YYYY-MM-DD, updated:>YYYY-MM-DD, updated:<YYYY-MM-DD
+
+## Important Note for Relative Date Queries:
+**CRITICAL: Always get today's actual date from the system before processing
+relative date queries (e.g., "today", "yesterday", "last week", "recent").
+When searching, apply these strategies:
+1. Convert concepts to technical terms (e.g., general descriptions → specific property names, method names, or technical keywords)
+2. Translate between Japanese and English technical terms (e.g., Japanese concepts → English API/property names)
+3. Expand to related technical elements (e.g., one concept → multiple implementation approaches, related technologies, or alternative solutions)
+IMPORTANT: Space-separated terms are treated as AND conditions. Use "OR" operator for alternative terms: "word-break OR word-wrap OR overflow-wrap".
+Advanced search: "tag:release", "category:dev", "wip:false", "keyword:API", "title:設計書".
+Category search: "on:category" (posts directly in category), "in:category" (posts in category and subcategories), "on:/" (uncategorized posts).
+For broader results, use OR between related terms rather than listing them with spaces.`).transform(be),sort:a.enum([`updated`,`created`,`number`,`stars`,`watches`,`comments`,`best_match`]).optional().describe(`Sort key`),order:a.enum([`desc`,`asc`]).optional().describe(`Sort direction`),page:a.number().int().positive().optional().describe(`Page number`),perPage:a.number().int().min(1).max(100).optional().describe(`Items per page`),include:a.enum([`comments`]).optional().describe(`Specify 'comments' to include comments in the response`)});async function Q(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/posts`,{params:{path:{team_name:t.teamName},query:{q:t.query,sort:t.sort,order:t.order,page:t.page,per_page:t.perPage,include:t.include}}});if(r||!i.ok)return v(r||i.status);let a=n.posts.map(e=>S(e,{truncateBody:500}));return h(a)}catch(e){return v(e)}}const $={TEAM:`docs`,SEARCH_OPTIONS_POST_ID:104,MARKDOWN_SYNTAX_POST_ID:49},xe=Z.omit({teamName:!0,order:!0,include:!0,sort:!0});async function Se(e,t){return J(e,{teamName:$.TEAM,postNumber:$.SEARCH_OPTIONS_POST_ID})}async function Ce(e,t){return J(e,{teamName:$.TEAM,postNumber:$.MARKDOWN_SYNTAX_POST_ID})}async function we(e,t){return Q(e,{teamName:$.TEAM,sort:`best_match`,...t})}const Te=T({postNumber:a.number().describe(`The post number to archive`),message:a.string().optional().describe(`Archive message for the post`)});async function Ee(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/posts/{post_number}`,{params:{path:{team_name:t.teamName,post_number:t.postNumber}}});if(r||!i.ok)return v(r||i.status);let a=n.category||``;if(a.startsWith(`Archived/`))return h({message:`Post is already archived`,category:a});let o=a===``?`Archived`:`Archived/${a}`;return await X(e,{teamName:t.teamName,postNumber:t.postNumber,category:o,message:t.message||`Archive post`})}catch(e){return v(e)}}const De=T({postNumber:a.number().describe(`The post number to ship`)});async function Oe(e,t){try{if(!t.teamName)throw new p;return await X(e,{teamName:t.teamName,postNumber:t.postNumber,wip:!1,message:`Ship It!`})}catch(e){return v(e)}}const ke=T({postNumber:a.number().describe(`The source post number to prepare for duplication`),targetTeamName:a.string().optional().describe(`The name of the esa team`).transform(e=>e?C(e):void 0)});async function Ae(e,t){try{if(!t.teamName)throw new p;let{data:n,error:r,response:i}=await e.GET(`/v1/teams/{team_name}/posts/new`,{params:{path:{team_name:t.teamName},query:{parent_post_id:t.postNumber}}});if(r||!i.ok)return v(r||i.status);let a=n.post;return Y(e,{teamName:t.targetTeamName||t.teamName,name:a.name,bodyMd:a.body_md,wip:!0})}catch(e){return v(e)}}function je(e,t){console.error(`Setting up MCP tools...`),e.registerTool(`esa_get_teams`,{title:`Get user's accessible esa teams`,description:`Retrieves a list of esa teams that the user has access to.`,inputSchema:E.shape},async e=>f(t,D,e)),e.registerTool(`esa_get_team_stats`,{title:`Get team statistics`,description:`Retrieves team statistics including member count, posts count (total/WIP/shipped), comments, stars, watches, and daily/weekly/monthly active users`,inputSchema:O.shape},async e=>f(t,k,e)),e.registerTool(`esa_get_team_tags`,{title:`Get team tags`,description:`Retrieves all tags used in posts within a team, along with the count of posts for each tag`,inputSchema:A.shape},async e=>f(t,j,e)),e.registerTool(`esa_get_team_members`,{title:`Get team members`,description:`Retrieves all members of a team with their roles and profile information`,inputSchema:M.shape},async e=>f(t,N,e)),e.registerTool(`esa_get_post`,{title:`Get a specific esa post`,description:`Retrieves a specific post from an esa team by post number, with optional comments included.`,inputSchema:_e.shape},async e=>f(t,J,e)),e.registerTool(`esa_search_posts`,{title:`Search Posts`,description:`Search for posts in esa.io`,inputSchema:Z.shape},async e=>f(t,Q,e)),e.registerTool(`esa_create_post`,{title:`Create a new esa post`,description:`Creates a new post in an esa team with optional tags, category, and WIP status.`,inputSchema:ve.shape},async e=>f(t,Y,e)),e.registerTool(`esa_update_post`,{title:`Update an existing esa post`,description:`Updates an existing post in an esa team by post number. You can update the title, content, tags, category, and WIP status. To ship a post (mark as complete), set wip to false - this is preferred over using esa_ship_post when updating other fields simultaneously.`,inputSchema:ye.shape},async e=>f(t,X,e)),e.registerTool(`esa_get_comment`,{title:`Get a specific comment`,description:`Retrieves a specific comment by comment ID, with optional stargazers included.`,inputSchema:U.shape},async e=>f(t,W,e)),e.registerTool(`esa_create_comment`,{title:`Create a new comment on a post`,description:`Creates a new comment on an existing post in an esa team.`,inputSchema:G.shape},async e=>f(t,K,e)),e.registerTool(`esa_update_comment`,{title:`Update an existing comment`,description:`Updates an existing comment in an esa team by comment ID.`,inputSchema:le.shape},async e=>f(t,ue,e)),e.registerTool(`esa_delete_comment`,{title:`Delete a comment`,description:`Deletes a comment from an esa team by comment ID.`,inputSchema:de.shape},async e=>f(t,fe,e)),e.registerTool(`esa_get_post_comments`,{title:`Get comments for a specific post`,description:`Retrieves a list of comments for a specific post with pagination support.`,inputSchema:pe.shape},async e=>f(t,me,e)),e.registerTool(`esa_get_team_comments`,{title:`Get team comments`,description:`Retrieves a list of comments in a team with pagination support.`,inputSchema:he.shape},async e=>f(t,ge,e)),e.registerTool(`esa_get_categories`,{title:`Get categories for a specific path`,description:`Retrieves category information and subcategories for a specific category path, with optional posts and parent categories included`,inputSchema:R.shape},async e=>f(t,z,e)),e.registerTool(`esa_get_top_categories`,{title:`Get top-level categories`,description:`Retrieves all top-level categories for a team`,inputSchema:B.shape},async e=>f(t,V,e)),e.registerTool(`esa_archive_post`,{title:`Archive a post`,description:`Archives a post by moving it to the Archived/ category. If the post is in 'dev/docs', it becomes 'Archived/dev/docs'. Posts without category go to 'Archived'.`,inputSchema:Te.shape},async e=>f(t,Ee,e)),e.registerTool(`esa_ship_post`,{title:`Ship a post`,description:`Ships a post by setting wip to false. This marks the post as complete and ready to be published. Use this only when you need to ship without making other changes - if you're also updating title, content, or other fields, use esa_update_post with wip: false instead.`,inputSchema:De.shape},async e=>f(t,Oe,e)),e.registerTool(`esa_duplicate_post`,{title:`Prepare a post for duplication`,description:`Prepares a post for duplication by retrieving its name and body_md content. Returns the name and body_md that can be used with esa_create_post to create a duplicate of the original post.`,inputSchema:ke.shape},async e=>f(t,Ae,e)),e.registerTool(`esa_get_search_options_help`,{title:`Get esa search options documentation`,description:`Get esa search syntax documentation when you need to construct complex
+search queries. Use this BEFORE esa_search_posts if you're unsure how to
+translate user's search requirements into proper esa query syntax (e.g., date
+ranges, tag filters, category searches, advanced operators).`,inputSchema:{}},async e=>f(t,Se,e)),e.registerTool(`esa_get_markdown_syntax_help`,{title:`Get esa Markdown syntax documentation`,description:`Get esa Markdown and formatting documentation when unsure about syntax.
+Use this BEFORE using any tools with *_md parameters (like esa_create_post,
+esa_update_post, esa_create_comment, esa_update_comment) if you need
+clarification on Markdown syntax, esa-specific extensions, or formatting options.`,inputSchema:{}},async e=>f(t,Ce,e)),e.registerTool(`esa_search_help`,{title:`Search esa documentation and help`,description:`Search esa documentation for features, terminology, and specifications.
+Use this when users mention esa-specific terms, ask about esa functionality,
+or request help with esa workflows that you're not familiar with.`,inputSchema:xe.shape},async e=>f(t,we,e))}try{c()}catch(e){console.error(`Configuration error:`,e),process.exit(1)}async function Me(){await ne();let t=new e({name:s.server.name,version:s.server.version});je(t,s.esa),F(t,s.esa),oe(t,s.esa);let r=new n;r.onclose=()=>{console.error(`Transport closed`)},r.onerror=e=>{console.error(`Transport error:`,e)},await t.connect(r),console.error(`${s.server.name} v${s.server.version} started`)}await Me().catch(e=>{console.error(`Server startup error:`,e),process.exit(1)});export{};

package/biome.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "complexity": {
+        "noForEach": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noConsole": "off"
+      },
+      "style": {
+        "useFilenamingConvention": {
+          "level": "error",
+          "options": {
+            "filenameCases": ["kebab-case"]
+          }
+        }
+      }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "formatWithErrors": false,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 80,
+    "lineEnding": "lf"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!**/node_modules",
+      "!**/bin",
+      "!**/coverage",
+      "!**/*.config.js",
+      "!**/*.config.ts",
+      "!.claude"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@esaio/esa-mcp-server",
+  "version": "0.1.0",
+  "description": "Official MCP server for esa.io - STDIO transport version",
+  "main": "bin/index.js",
+  "type": "module",
+  "bin": {
+    "esa-mcp-server": "./bin/index.js"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "esa",
+    "esa.io",
+    "documentation",
+    "knowledge-base"
+  ],
+  "author": "esa LLC",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "i18next": "^25.5.2",
+    "openapi-fetch": "^0.14.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.4",
+    "@types/node": "^20.19.14",
+    "@vitest/coverage-v8": "^3.2.4",
+    "openapi-typescript": "^7.9.1",
+    "tsdown": "^0.15.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.19.4"
+  }
+}

package/src/__tests__/fixtures/mock-comment.ts

@@ -0,0 +1,90 @@
+import type { components } from "../../generated/api-types.js";
+import { transformComment } from "../../transformers/comment-transformer.js";
+
+export function createMockComment(
+  overrides?: Partial<components["schemas"]["Comment"]>,
+): components["schemas"]["Comment"] {
+  return {
+    id: 123,
+    post_number: 456,
+    body_md: "This is a test comment content",
+    body_html: "<p>This is a test comment content</p>",
+    created_at: "2024-01-01T00:00:00+09:00",
+    updated_at: "2024-01-01T01:00:00+09:00",
+    url: "https://test-team.esa.example.com/posts/456#comment-123",
+    created_by: {
+      name: "Test User",
+      screen_name: "testuser",
+      icon: "https://example.com/icon.png",
+      myself: true,
+    },
+    stargazers_count: 5,
+    star: true,
+    stargazers: [
+      {
+        created_at: "2024-01-01T02:00:00+09:00",
+        body: "Great comment!",
+        user: {
+          name: "Stargazer User",
+          screen_name: "stargazer",
+          icon: "https://example.com/star-icon.png",
+          myself: false,
+        },
+        name: "Stargazer User",
+        screen_name: "stargazer",
+        icon: "https://example.com/star-icon.png",
+        myself: false,
+        email: "stargazer@example.com",
+        role: "member" as const,
+        posts_count: 10,
+        joined_at: "2024-01-01T00:00:00+09:00",
+        last_accessed_at: "2024-01-01T02:00:00+09:00",
+      },
+    ],
+    ...overrides,
+  };
+}
+
+export function createLongContentComment(
+  length: number,
+): components["schemas"]["Comment"] {
+  const longContent = "a".repeat(length);
+  return createMockComment({
+    body_md: longContent,
+    body_html: `<p>${longContent}</p>`,
+  });
+}
+
+export function createNullBodyComment(
+  overrides?: Partial<components["schemas"]["Comment"]>,
+): components["schemas"]["Comment"] {
+  return createMockComment({
+    body_md: "",
+    body_html: "",
+    ...overrides,
+  });
+}
+
+export function createExpectedTransformedComment(
+  comment: components["schemas"]["Comment"],
+) {
+  return transformComment(comment);
+}
+
+export function createMockCommentList(
+  overrides?: Partial<components["schemas"]["CommentList"]>,
+): components["schemas"]["CommentList"] {
+  return {
+    comments: [
+      createMockComment({ id: 1, post_number: 123, body_md: "First comment" }),
+      createMockComment({ id: 2, post_number: 124, body_md: "Second comment" }),
+    ],
+    prev_page: null,
+    next_page: 2,
+    total_count: 10,
+    page: 1,
+    per_page: 20,
+    max_per_page: 100,
+    ...overrides,
+  };
+}

package/src/__tests__/fixtures/mock-post.ts

@@ -0,0 +1,79 @@
+import type { components } from "../../generated/api-types.js";
+import {
+  type PostTransformOptions,
+  transformPost,
+} from "../../transformers/post-transformer.js";
+
+export const createMockPost = (
+  overrides: Partial<components["schemas"]["Post"]> = {},
+): components["schemas"]["Post"] => ({
+  number: 123,
+  name: "test-post.md",
+  tags: ["tag1", "tag2"],
+  category: "dev",
+  full_name: "dev/test-post.md #tag1 #tag2",
+  wip: false,
+  body_md: "# Test Post\n\nThis is a test post content.",
+  body_html: "<h1>Test Post</h1><p>This is a test post content.</p>",
+  created_at: "2024-01-01T00:00:00+09:00",
+  updated_at: "2024-01-02T00:00:00+09:00",
+  message: "Update test post",
+  url: "https://test-team.esa.example.com/posts/123",
+  revision_number: 3,
+  created_by: {
+    name: "user1",
+    screen_name: "user1",
+    icon: "https://example.com/icon1.png",
+    myself: false,
+  },
+  updated_by: {
+    name: "user2",
+    screen_name: "user2",
+    icon: "https://example.com/icon2.png",
+    myself: false,
+  },
+  kind: "stock",
+  comments_count: 5,
+  tasks_count: 3,
+  done_tasks_count: 2,
+  stargazers_count: 10,
+  watchers_count: 8,
+  star: true,
+  watch: false,
+  ...overrides,
+});
+
+export const createWipPost = (
+  overrides: Partial<components["schemas"]["Post"]> = {},
+): components["schemas"]["Post"] =>
+  createMockPost({
+    wip: true,
+    number: 456,
+    name: "wip-post.md",
+    full_name: "docs/wip-post.md #wip",
+    url: "https://test-team.esa.example.com/posts/456",
+    kind: "flow",
+    ...overrides,
+  });
+
+export const createLongContentPost = (
+  contentLength = 600,
+): components["schemas"]["Post"] =>
+  createMockPost({
+    body_md: "a".repeat(contentLength),
+    body_html: `<p>${"a".repeat(contentLength)}</p>`,
+  });
+
+export const createNullBodyPost = (
+  overrides: Partial<components["schemas"]["Post"]> = {},
+): components["schemas"]["Post"] =>
+  createMockPost({
+    body_md: undefined,
+    body_html: undefined,
+    ...overrides,
+  });
+
+export const createExpectedTransformed = (
+  post: components["schemas"]["Post"],
+  options: PostTransformOptions = {},
+) => transformPost(post, options);

package/src/__tests__/index.test.ts

@@ -0,0 +1,209 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { MockInstance } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("MCP Server", () => {
+  let consoleErrorSpy: MockInstance<typeof console.error>;
+  let processExitSpy: MockInstance<typeof process.exit>;
+
+  const createMockConfig = (behavior?: { shouldThrow?: boolean }) => ({
+    config: {
+      server: {
+        name: "test-server",
+        version: "1.0.0",
+      },
+      esa: {
+        apiAccessToken: "test-token",
+        apiBaseUrl: "https://api.esa.example.com",
+      },
+    },
+    validateConfig: vi.fn().mockImplementation(() => {
+      if (behavior?.shouldThrow) {
+        throw new Error("Invalid config");
+      }
+    }),
+  });
+
+  const createMockServer = (behavior?: { shouldFailConnect?: boolean }) => {
+    const mockConnect = behavior?.shouldFailConnect
+      ? vi.fn().mockRejectedValue(new Error("Connection failed"))
+      : vi.fn().mockResolvedValue(undefined);
+
+    return {
+      connect: mockConnect,
+    } as unknown as McpServer;
+  };
+
+  const createMockTransport = () =>
+    ({
+      onclose: undefined as (() => void) | undefined,
+      onerror: undefined as ((error: Error) => void) | undefined,
+    }) as unknown as StdioServerTransport;
+
+  const setupServerMocks = (
+    mockConfig: ReturnType<typeof createMockConfig>,
+    mockServer: ReturnType<typeof createMockServer>,
+    mockTransport: ReturnType<typeof createMockTransport>,
+    setupFunctions?: {
+      setupTools?: ReturnType<typeof vi.fn>;
+      setupResources?: ReturnType<typeof vi.fn>;
+      setupPrompts?: ReturnType<typeof vi.fn>;
+      initI18n?: ReturnType<typeof vi.fn>;
+    },
+  ) => {
+    const MockMcpServer = vi.fn().mockReturnValue(mockServer);
+    const MockStdioServerTransport = vi.fn().mockReturnValue(mockTransport);
+
+    vi.doMock("../config/index.js", () => mockConfig);
+    vi.doMock("@modelcontextprotocol/sdk/server/mcp.js", () => ({
+      McpServer: MockMcpServer,
+    }));
+    vi.doMock("@modelcontextprotocol/sdk/server/stdio.js", () => ({
+      StdioServerTransport: MockStdioServerTransport,
+    }));
+    vi.doMock("../tools/index.js", () => ({
+      setupTools: setupFunctions?.setupTools ?? vi.fn(),
+    }));
+    vi.doMock("../resources/index.js", () => ({
+      setupResources: setupFunctions?.setupResources ?? vi.fn(),
+    }));
+    vi.doMock("../prompts/index.js", () => ({
+      setupPrompts: setupFunctions?.setupPrompts ?? vi.fn(),
+    }));
+    vi.doMock("../i18n/index.js", () => ({
+      initI18n:
+        setupFunctions?.initI18n ?? vi.fn().mockResolvedValue(undefined),
+    }));
+
+    return { MockMcpServer, MockStdioServerTransport };
+  };
+
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    processExitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+    processExitSpy.mockRestore();
+    vi.resetModules();
+  });
+
+  it("should validate config on startup", async () => {
+    const mockConfig = createMockConfig();
+    const mockServer = createMockServer();
+    const mockTransport = createMockTransport();
+
+    setupServerMocks(mockConfig, mockServer, mockTransport);
+
+    await import("../index.js");
+
+    expect(mockConfig.validateConfig).toHaveBeenCalled();
+  });
+
+  it("should exit with error when config validation fails", async () => {
+    const mockConfig = createMockConfig({ shouldThrow: true });
+
+    vi.doMock("../config/index.js", () => mockConfig);
+
+    try {
+      await import("../index.js");
+    } catch (_error) {
+      // Expected to throw due to config validation
+    }
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      "Configuration error:",
+      expect.any(Error),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it("should create MCP server and connect", async () => {
+    const mockConfig = createMockConfig();
+    const mockServer = createMockServer();
+    const mockTransport = createMockTransport();
+
+    // Track setup function calls
+    const mockSetupTools = vi.fn();
+    const mockSetupResources = vi.fn();
+    const mockSetupPrompts = vi.fn();
+
+    const { MockMcpServer } = setupServerMocks(
+      mockConfig,
+      mockServer,
+      mockTransport,
+      {
+        setupTools: mockSetupTools,
+        setupResources: mockSetupResources,
+        setupPrompts: mockSetupPrompts,
+      },
+    );
+
+    await import("../index.js");
+
+    expect(MockMcpServer).toHaveBeenCalledWith({
+      name: "test-server",
+      version: "1.0.0",
+    });
+
+    const expectedEsaConfig = {
+      apiAccessToken: "test-token",
+      apiBaseUrl: "https://api.esa.example.com",
+    };
+
+    expect(mockSetupTools).toHaveBeenCalledWith(mockServer, expectedEsaConfig);
+    expect(mockSetupResources).toHaveBeenCalledWith(
+      mockServer,
+      expectedEsaConfig,
+    );
+    expect(mockSetupPrompts).toHaveBeenCalledWith(
+      mockServer,
+      expectedEsaConfig,
+    );
+    expect(mockServer.connect).toHaveBeenCalled();
+    expect(consoleErrorSpy).toHaveBeenCalledWith("test-server v1.0.0 started");
+  });
+
+  it("should set up transport error handlers", async () => {
+    const mockConfig = createMockConfig();
+    const mockServer = createMockServer();
+    const mockTransport = createMockTransport();
+
+    setupServerMocks(mockConfig, mockServer, mockTransport);
+
+    await import("../index.js");
+
+    expect(mockTransport.onclose).toBeDefined();
+    expect(mockTransport.onerror).toBeDefined();
+
+    mockTransport.onclose?.();
+    expect(consoleErrorSpy).toHaveBeenCalledWith("Transport closed");
+
+    const testError = new Error("Test error");
+    mockTransport.onerror?.(testError);
+    expect(consoleErrorSpy).toHaveBeenCalledWith("Transport error:", testError);
+  });
+
+  it("should handle server startup errors", async () => {
+    const mockConfig = createMockConfig();
+    const mockServer = createMockServer({ shouldFailConnect: true });
+    const mockTransport = createMockTransport();
+
+    setupServerMocks(mockConfig, mockServer, mockTransport);
+
+    await import("../index.js");
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      "Server startup error:",
+      expect.any(Error),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+});