@esaio/esa-mcp-server 0.3.1 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/index.js +9 -5
- package/package.json +1 -1
package/bin/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
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=`0.
|
|
2
|
+
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=`0.4.0`;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,description:`Official MCP server for esa.io`}};function c(){if(!s.esa.apiAccessToken)throw Error(`ESA_ACCESS_TOKEN environment variable is required`)}var l={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)`}}}},ee={prompts:{summarize_post:{title:`esaの記事の要約`,description:`esa記事を指定した形式で要約します(bullet: 箇条書き, paragraph: 文章, keywords: キーワード)`,args:{team_name:`esaチーム名`,post_number:`要約する記事番号`,format:`要約形式 (bullet/paragraph/keywords)`}}}};async function te(){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`,showSupportNotice:!1,resources:{ja:{translation:ee},en:{translation:l}},interpolation:{escapeValue:!1}}),r}function u(e,t){return r.t(e,t)}function d(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 ne=o;function re(e){return{async onRequest({request:t}){return t.headers.set(`User-Agent`,`esa-mcp-server/${e} (official)`),t}}}function ie(e,t=`https://api.esa.io`){let n=i({baseUrl:t});return n.use(re(ne)),n.use(d(e)),n}async function f(e,t,...n){let r;if(`apiAccessToken`in e&&`apiBaseUrl`in e)r=ie(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 ae=()=>a.object({teamName:a.string().describe(u(`prompts.summarize_post.args.team_name`)),postNumber:a.string().describe(u(`prompts.summarize_post.args.post_number`)),format:a.enum([`bullet`,`paragraph`,`keywords`]).optional().describe(u(`prompts.summarize_post.args.format`))});async function oe(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:
|
|
3
3
|
|
|
4
4
|
`;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+=`
|
|
5
5
|
---
|
|
@@ -19,12 +19,16 @@ When searching, apply these strategies:
|
|
|
19
19
|
IMPORTANT: Space-separated terms are treated as AND conditions. Use "OR" operator for alternative terms: "word-break OR word-wrap OR overflow-wrap".
|
|
20
20
|
Advanced search: "tag:release", "category:dev", "wip:false", "keyword:API", "title:設計書".
|
|
21
21
|
Category search: "on:category" (posts directly in category), "in:category" (posts in category and subcategories), "on:/" (uncategorized posts).
|
|
22
|
-
For broader results, use OR between related terms rather than listing them with spaces.`).transform(ke),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 Z(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}}});
|
|
22
|
+
For broader results, use OR between related terms rather than listing them with spaces.`).transform(ke),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 Z(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,o=a.map(e=>x(e,{truncateBody:500}));return a.length===0&&Ae(t.query)?{content:[{type:`text`,text:je(t.query)}]}:h(o)}catch(e){return v(e)}}function Ae(e){return!e||e.trim()===``||/\bOR\b/.test(e)||e.includes(`|`)?!1:e.split(/\s+/).filter(Boolean).length>=2}function je(e){return`---
|
|
23
|
+
No results found. Your query uses AND conditions (space-separated terms).
|
|
24
|
+
Suggestions:
|
|
25
|
+
- Try OR search: "${e.split(/\s+/).filter(Boolean).join(` OR `)}"
|
|
26
|
+
- Omit some keywords from your query`}const Q={TEAM:`docs`,SEARCH_OPTIONS_POST_ID:104,MARKDOWN_SYNTAX_POST_ID:49},Me=X.omit({teamName:!0,order:!0,include:!0,sort:!0});async function Ne(e,t){return q(e,{teamName:Q.TEAM,postNumber:Q.SEARCH_OPTIONS_POST_ID})}async function Pe(e,t){return q(e,{teamName:Q.TEAM,postNumber:Q.MARKDOWN_SYNTAX_POST_ID})}async function Fe(e,t){return Z(e,{teamName:Q.TEAM,sort:`best_match`,...t})}const Ie=w({postNumber:a.number().describe(`The post number to archive`),message:a.string().optional().describe(`Archive message for the post`)});async function Le(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 Y(e,{teamName:t.teamName,postNumber:t.postNumber,category:o,message:t.message||`Archive post`})}catch(e){return v(e)}}const $=w({postNumber:a.number().describe(`The post number to ship`)});async function Re(e,t){try{if(!t.teamName)throw new p;return await Y(e,{teamName:t.teamName,postNumber:t.postNumber,wip:!1,message:`Ship It!`})}catch(e){return v(e)}}const ze=w({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?S(e):void 0)});async function Be(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 J(e,{teamName:t.targetTeamName||t.teamName,name:a.name,bodyMd:a.body_md,wip:!0})}catch(e){return v(e)}}function Ve(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:T.shape,annotations:{readOnlyHint:!0}},async e=>f(t,E,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:D.shape,annotations:{readOnlyHint:!0}},async e=>f(t,O,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:k.shape,annotations:{readOnlyHint:!0}},async e=>f(t,A,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:j.shape,annotations:{readOnlyHint:!0}},async e=>f(t,M,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:Ee.shape,annotations:{readOnlyHint:!0}},async e=>f(t,q,e)),e.registerTool(`esa_search_posts`,{title:`Search Posts`,description:`Search for posts in esa.io`,inputSchema:X.shape,annotations:{readOnlyHint:!0}},async e=>f(t,Z,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:De.shape,annotations:{destructiveHint:!0}},async e=>f(t,J,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:Oe.shape,annotations:{destructiveHint:!0}},async e=>f(t,Y,e)),e.registerTool(`esa_get_comment`,{title:`Get a specific comment`,description:`Retrieves a specific comment by comment ID, with optional stargazers included.`,inputSchema:me.shape,annotations:{readOnlyHint:!0}},async e=>f(t,he,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:ge.shape,annotations:{destructiveHint:!0}},async e=>f(t,_e,e)),e.registerTool(`esa_update_comment`,{title:`Update an existing comment`,description:`Updates an existing comment in an esa team by comment ID.`,inputSchema:ve.shape,annotations:{destructiveHint:!0}},async e=>f(t,ye,e)),e.registerTool(`esa_delete_comment`,{title:`Delete a comment`,description:`Deletes a comment from an esa team by comment ID.`,inputSchema:be.shape,annotations:{destructiveHint:!0}},async e=>f(t,xe,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:Se.shape,annotations:{readOnlyHint:!0}},async e=>f(t,Ce,e)),e.registerTool(`esa_get_team_comments`,{title:`Get team comments`,description:`Retrieves a list of comments in a team with pagination support.`,inputSchema:we.shape,annotations:{readOnlyHint:!0}},async e=>f(t,Te,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:U.shape,annotations:{readOnlyHint:!0}},async e=>f(t,W,e)),e.registerTool(`esa_get_top_categories`,{title:`Get top-level categories`,description:`Retrieves all top-level categories for a team`,inputSchema:ue.shape,annotations:{readOnlyHint:!0}},async e=>f(t,de,e)),e.registerTool(`esa_get_all_category_paths`,{title:`Get category paths with pagination`,description:`Retrieves category paths in a team to understand the overall category structure. Perfect for category organization, cleanup, migration planning, or finding similar categories. Returns a paginated list of paths with post counts, sorted in lexicographic order. Supports filtering (prefix/suffix/match/exact_match) to find categories by pattern.`,inputSchema:fe.shape,annotations:{readOnlyHint:!0}},async e=>f(t,pe,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:Ie.shape,annotations:{destructiveHint:!0}},async e=>f(t,Le,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:$.shape,annotations:{destructiveHint:!0}},async e=>f(t,Re,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:ze.shape,annotations:{destructiveHint:!0}},async e=>f(t,Be,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
|
|
23
27
|
search queries. Use this BEFORE esa_search_posts if you're unsure how to
|
|
24
28
|
translate user's search requirements into proper esa query syntax (e.g., date
|
|
25
|
-
ranges, tag filters, category searches, advanced operators).`,inputSchema:{},annotations:{readOnlyHint:!0}},async e=>f(t
|
|
29
|
+
ranges, tag filters, category searches, advanced operators).`,inputSchema:{},annotations:{readOnlyHint:!0}},async e=>f(t,Ne,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.
|
|
26
30
|
Use this BEFORE using any tools with *_md parameters (like esa_create_post,
|
|
27
31
|
esa_update_post, esa_create_comment, esa_update_comment) if you need
|
|
28
|
-
clarification on Markdown syntax, esa-specific extensions, or formatting options.`,inputSchema:{},annotations:{readOnlyHint:!0}},async e=>f(t,
|
|
32
|
+
clarification on Markdown syntax, esa-specific extensions, or formatting options.`,inputSchema:{},annotations:{readOnlyHint:!0}},async e=>f(t,Pe,e)),e.registerTool(`esa_search_help`,{title:`Search esa documentation and help`,description:`Search esa documentation for features, terminology, and specifications.
|
|
29
33
|
Use this when users mention esa-specific terms, ask about esa functionality,
|
|
30
|
-
or request help with esa workflows that you're not familiar with.`,inputSchema:
|
|
34
|
+
or request help with esa workflows that you're not familiar with.`,inputSchema:Me.shape,annotations:{readOnlyHint:!0}},async e=>f(t,Fe,e)),e.registerTool(`esa_get_attachment`,{title:`Get attachment file from esa`,description:`Retrieves an attachment file from esa with signed URLs. For supported images (JPEG, PNG, GIF, WebP) under 30MB, returns base64-encoded data. For other file types, larger images, or when forceSignedUrl is true, returns signed URLs.`,inputSchema:I.shape,annotations:{readOnlyHint:!0}},async e=>f(t,B,e))}try{c()}catch(e){console.error(`Configuration error:`,e),process.exit(1)}async function He(){await te();let t=new e({name:s.server.name,version:s.server.version});Ve(t,s.esa),P(t,s.esa),se(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 He().catch(e=>{console.error(`Server startup error:`,e),process.exit(1)});export{};
|