@aashari/boilerplate-mcp-server 1.4.2 → 1.4.3

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.
Files changed (10) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +2 -3
  3. package/STYLE_GUIDE.md +17 -0
  4. package/dist/cli/ipaddress.cli.js +5 -5
  5. package/dist/tools/ipaddress.tool.js +1 -1
  6. package/dist/tools/ipaddress.types.js +2 -2
  7. package/dist/utils/constants.util.d.ts +1 -1
  8. package/dist/utils/constants.util.js +1 -1
  9. package/package.json +1 -1
  10. package/package.json.bak +1 -1
package/CHANGELOG.md CHANGED
@@ -1,3 +1,11 @@
1
+ ## [1.4.3](https://github.com/aashari/boilerplate-mcp-server/compare/v1.4.2...v1.4.3) (2025-05-01)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * Align CLI options and descriptions with style guide ([0f5f490](https://github.com/aashari/boilerplate-mcp-server/commit/0f5f4901f69ea80d03688b289b0cd59599957740))
7
+ * align README tool example with concise description style ([b8126a4](https://github.com/aashari/boilerplate-mcp-server/commit/b8126a4b4f8286cfefeb9c50f53aaea7e9f90982))
8
+
1
9
  ## [1.4.2](https://github.com/aashari/boilerplate-mcp-server/compare/v1.4.1...v1.4.2) (2025-05-01)
2
10
 
3
11
 
package/README.md CHANGED
@@ -276,9 +276,8 @@ async function handleGetData(args: GetDataArgsType) {
276
276
  export function register(server: McpServer) {
277
277
  server.tool(
278
278
  'get_data',
279
- `PURPOSE: Get data from the example API.
280
- RETURNS: Markdown with formatted data.
281
- EXAMPLES: { "param": "value" }`,
279
+ `Gets data from the example API, optionally using \`param\`.
280
+ Use this to fetch example data. Returns formatted data as Markdown.`,
282
281
  GetDataArgs.shape,
283
282
  handleGetData,
284
283
  );
package/STYLE_GUIDE.md ADDED
@@ -0,0 +1,17 @@
1
+ # MCP Server Style Guide
2
+
3
+ Based on the patterns observed and best practices, I recommend adopting the following consistent style guide across all your MCP servers:
4
+
5
+ | Element | Convention | Rationale / Examples |
6
+ | :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
7
+ | **CLI Commands** | `verb-noun` in `kebab-case`. Use the shortest unambiguous verb (`ls`, `get`, `create`, `add`, `exec`, `search`). | `ls-repos`, `get-pr`, `create-comment`, `exec-command` |
8
+ | **CLI Options** | `--kebab-case`. Be specific (e.g., `--workspace-slug`, not just `--slug`). | `--project-key-or-id`, `--source-branch` |
9
+ | **MCP Tool Names** | `<namespace>_<verb>_<noun>` in `snake_case`. Use a concise 2-4 char namespace. Avoid noun repetition. | `bb_ls_repos` (Bitbucket list repos), `conf_get_page` (Confluence get page), `aws_exec_command` (AWS execute command). Avoid `ip_ip_get_details`. |
10
+ | **MCP Arguments** | `camelCase`. Suffix identifiers consistently (e.g., `Id`, `Key`, `Slug`). Avoid abbreviations unless universal. | `workspaceSlug`, `pullRequestId`, `sourceBranch`, `pageId`. |
11
+ | **Boolean Args** | Use verb prefixes for clarity (`includeXxx`, `launchBrowser`). Avoid bare adjectives (`--https`). | `includeExtendedData: boolean`, `launchBrowser: boolean` |
12
+ | **Array Args** | Use plural names (`spaceIds`, `labels`, `statuses`). | `spaceIds: string[]`, `labels: string[]` |
13
+ | **Descriptions** | **Start with an imperative verb.** Keep the first sentence concise (≤120 chars). Add 1-2 sentences detail. Mention pre-requisites/notes last. | `List available Confluence spaces. Filters by type, status, or query. Returns formatted list including ID, key, name.` |
14
+ | **Arg Descriptions** | Start lowercase, explain purpose clearly. Mention defaults or constraints. | `numeric ID of the page to retrieve (e.g., "456789"). Required.` |
15
+ | **ID/Key Naming** | Use consistent suffixes like `Id`, `Key`, `Slug`, `KeyOrId` where appropriate. | `pageId`, `projectKeyOrId`, `workspaceSlug` |
16
+
17
+ Adopting this guide will make the tools more predictable and easier for both humans and AI agents to understand and use correctly.
package/dist/cli/ipaddress.cli.js CHANGED
@@ -15,18 +15,18 @@ function register(program) {
15
15
  cliLogger.debug(`Registering IP address CLI commands...`);
16
16
  program
17
17
  .command('get-ip-details')
18
- .description(`Get geolocation and network details about an IP address or the current device.`)
18
+ .description(`Gets geolocation and network details about an IP address or the current device.`)
19
19
  .argument('[ipAddress]', 'IP address to lookup (omit for current IP)')
20
- .option('--extended', 'Include extended data like ASN, mobile and proxy detection')
21
- .option('--https', 'Use HTTPS for API requests (may require paid API key)')
20
+ .option('--include-extended', 'Includes extended data like ASN, mobile and proxy detection')
21
+ .option('--use-https', 'Uses HTTPS for API requests (Requires paid API tier)')
22
22
  .action(async (ipAddress, cmdOptions) => {
23
23
  const commandLogger = logger_util_js_1.Logger.forContext('cli/ipaddress.cli.ts', 'get-ip-details');
24
24
  try {
25
25
  commandLogger.debug(`Processing IP details request for ${ipAddress || 'current device'}`, cmdOptions);
26
26
  // Map CLI options to controller options
27
27
  const controllerOptions = {
28
- includeExtendedData: cmdOptions?.extended || false,
29
- useHttps: cmdOptions?.https || false,
28
+ includeExtendedData: cmdOptions?.includeExtended || false,
29
+ useHttps: cmdOptions?.useHttps || false,
30
30
  };
31
31
  commandLogger.debug('Calling controller with options', controllerOptions);
32
32
  const result = await ipaddress_controller_js_1.default.get(ipAddress, controllerOptions);
package/dist/tools/ipaddress.tool.js CHANGED
@@ -53,7 +53,7 @@ async function getIpAddressDetails(args) {
53
53
  function registerTools(server) {
54
54
  const methodLogger = logger_util_js_1.Logger.forContext('tools/ipaddress.tool.ts', 'registerTools');
55
55
  methodLogger.debug(`Registering IP address tools...`);
56
- server.tool('ip_get_details', `Retrieves geolocation and network details for a public IP address (\`ipAddress\`). If no IP is provided, returns details for the server's current public IP.\n- Fetches country, city, region, coordinates, ISP, and organization.\n- Optional \`includeExtendedData\` can provide reverse DNS, mobile/proxy/hosting detection.\nUse this to get geographical or network context for a public IP address.\nReturns formatted Markdown with location, network details, map link, and timestamp.\n**Note:** Does not work for private/reserved IP addresses. Relies on the external ip-api.com service.`, ipaddress_types_js_1.IpAddressToolArgs.shape, getIpAddressDetails);
56
+ server.tool('ip_get_details', `Retrieves geolocation and network details for a public IP address (\`ipAddress\`). Falls back to the server's current public IP if omitted. Fetches country, city, coordinates, ISP, etc. Optionally includes extended data (\`includeExtendedData\`) like ASN, mobile/proxy/hosting detection. **Note:** Does not work for private IPs. Relies on ip-api.com. Use \`useHttps\` for paid tier.`, ipaddress_types_js_1.IpAddressToolArgs.shape, getIpAddressDetails);
57
57
  methodLogger.debug('Successfully registered get-ip-details tool.');
58
58
  }
59
59
  exports.default = { registerTools };
package/dist/tools/ipaddress.types.js CHANGED
@@ -10,10 +10,10 @@ const IpAddressToolArgs = zod_1.z.object({
10
10
  includeExtendedData: zod_1.z
11
11
  .boolean()
12
12
  .optional()
13
- .describe('Include extended data like ASN, mobile and proxy detection'),
13
+ .describe('Includes extended data like ASN, mobile and proxy detection'),
14
14
  useHttps: zod_1.z
15
15
  .boolean()
16
16
  .optional()
17
- .describe('Use HTTPS for API requests (may require paid API key)'),
17
+ .describe('Uses HTTPS for API requests (may require paid API key)'),
18
18
  });
19
19
  exports.IpAddressToolArgs = IpAddressToolArgs;
package/dist/utils/constants.util.d.ts CHANGED
@@ -8,7 +8,7 @@
8
8
  * Current application version
9
9
  * This should match the version in package.json
10
10
  */
11
- export declare const VERSION = "1.4.2";
11
+ export declare const VERSION = "1.4.3";
12
12
  /**
13
13
  * Package name with scope
14
14
  * Used for initialization and identification
package/dist/utils/constants.util.js CHANGED
@@ -11,7 +11,7 @@ exports.CLI_NAME = exports.PACKAGE_NAME = exports.VERSION = void 0;
11
11
  * Current application version
12
12
  * This should match the version in package.json
13
13
  */
14
- exports.VERSION = '1.4.2';
14
+ exports.VERSION = '1.4.3';
15
15
  /**
16
16
  * Package name with scope
17
17
  * Used for initialization and identification
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aashari/boilerplate-mcp-server",
3
- "version": "1.4.2",
3
+ "version": "1.4.3",
4
4
  "description": "TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
package/package.json.bak CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aashari/boilerplate-mcp-server",
3
- "version": "1.4.1",
3
+ "version": "1.4.2",
4
4
  "description": "TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",