@aashari/boilerplate-mcp-server 1.0.0 → 1.0.2

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 (12) hide show
  1. package/.releaserc.json +2 -7
  2. package/CHANGELOG.md +47 -46
  3. package/README.md +106 -203
  4. package/dist/cli/index.js +1 -1
  5. package/dist/cli/index.js.bak +1 -1
  6. package/dist/index.js +3 -1
  7. package/dist/index.js.bak +3 -1
  8. package/dist/tools/ipaddress.tool.js +1 -1
  9. package/package.json +47 -1
  10. package/package.json.bak +47 -1
  11. package/scripts/update-version.js +18 -3
  12. package/jest.config.mjs +0 -19
package/.releaserc.json CHANGED
@@ -7,7 +7,7 @@
7
7
  [
8
8
  "@semantic-release/exec",
9
9
  {
10
- "prepareCmd": "node scripts/update-version.js ${nextRelease.version} && npm run build"
10
+ "prepareCmd": "node scripts/update-version.js ${nextRelease.version} && npm run build && chmod +x dist/index.js"
11
11
  }
12
12
  ],
13
13
  [
@@ -20,12 +20,7 @@
20
20
  [
21
21
  "@semantic-release/git",
22
22
  {
23
- "assets": [
24
- "package.json",
25
- "CHANGELOG.md",
26
- "src/index.ts",
27
- "dist/index.js"
28
- ],
23
+ "assets": ["package.json", "CHANGELOG.md", "src/index.ts"],
29
24
  "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
30
25
  }
31
26
  ],
package/CHANGELOG.md CHANGED
@@ -1,107 +1,108 @@
1
- # 1.0.0 (2025-03-22)
1
+ ## [1.0.2](https://github.com/aashari/boilerplate-mcp-server/compare/v1.0.1...v1.0.2) (2025-03-23)
2
2
 
3
3
 
4
4
  ### Bug Fixes
5
5
 
6
- * add workflows permission to semantic-release workflow ([de3a335](https://github.com/aashari/boilerplate-mcp-server/commit/de3a33510bd447af353444db1fcb58e1b1aa02e4))
7
- * improve GitHub Packages publishing with a more robust approach ([fd2aec9](https://github.com/aashari/boilerplate-mcp-server/commit/fd2aec9926cf99d301cbb2b5f5ca961a6b6fec7e))
8
- * improve GitHub Packages publishing with better error handling and debugging ([db25f04](https://github.com/aashari/boilerplate-mcp-server/commit/db25f04925e884349fcf3ab85316550fde231d1f))
9
- * improve GITHUB_OUTPUT syntax in semantic-release workflow ([6f154bc](https://github.com/aashari/boilerplate-mcp-server/commit/6f154bc43f42475857e9256b0a671c3263dc9708))
10
- * improve version detection for global installations ([97a95dc](https://github.com/aashari/boilerplate-mcp-server/commit/97a95dca61d8cd7a86c81bde4cb38c509b810dc0))
11
- * make publish workflow more resilient against version conflicts ([ffd3705](https://github.com/aashari/boilerplate-mcp-server/commit/ffd3705bc064ee9135402052a0dc7fe32645714b))
12
- * remove invalid workflows permission ([c012e46](https://github.com/aashari/boilerplate-mcp-server/commit/c012e46a29070c8394f7ab596fe7ba68c037d3a3))
13
- * remove type module to fix CommonJS compatibility ([8b1f00c](https://github.com/aashari/boilerplate-mcp-server/commit/8b1f00c37467bc676ad8ec9ab672ba393ed084a9))
14
- * resolve linter errors in version detection code ([5f1f33e](https://github.com/aashari/boilerplate-mcp-server/commit/5f1f33e88ae843b7a0d708899713be36fcd2ec2e))
15
- * update examples to use correct API (greet instead of sayHello) ([7c062ca](https://github.com/aashari/boilerplate-mcp-server/commit/7c062ca42765c659f018f990f4b1ec563d1172d3))
16
- * update release workflow to ensure correct versioning in compiled files ([a365394](https://github.com/aashari/boilerplate-mcp-server/commit/a365394b8596defa33ff5a44583d52e2c43f0aa3))
17
- * update version display in CLI ([2b7846c](https://github.com/aashari/boilerplate-mcp-server/commit/2b7846cbfa023f4b1a8c81ec511370fa8f5aaf33))
6
+ * improve error logging with IP address details ([121f516](https://github.com/aashari/boilerplate-mcp-server/commit/121f51655517ddbea7d25968372bd6476f1b3e0f))
18
7
 
8
+ ## [1.0.1](https://github.com/aashari/boilerplate-mcp-server/compare/v1.0.0...v1.0.1) (2025-03-23)
19
9
 
20
- ### Features
21
10
 
22
- * add automated dependency management ([efa1b62](https://github.com/aashari/boilerplate-mcp-server/commit/efa1b6292e0e9b6efd0d43b40cf7099d50769487))
23
- * add CLI usage examples for both JavaScript and TypeScript ([d5743b0](https://github.com/aashari/boilerplate-mcp-server/commit/d5743b07a6f2afe1c6cb0b03265228cba771e657))
24
- * add support for custom name in greet command ([be48a05](https://github.com/aashari/boilerplate-mcp-server/commit/be48a053834a1d910877864608a5e9942d913367))
25
- * add version update script and fix version display ([ec831d3](https://github.com/aashari/boilerplate-mcp-server/commit/ec831d3a3c966d858c15972365007f9dfd6115b8))
26
- * implement review recommendations ([a23cbc0](https://github.com/aashari/boilerplate-mcp-server/commit/a23cbc0608a07e202396b3cd496c1f2078e304c1))
27
- * implement testing, linting, and semantic versioning ([1d7710d](https://github.com/aashari/boilerplate-mcp-server/commit/1d7710dfa11fd1cb04ba3c604e9a2eb785652394))
28
- * improve CI workflows with standardized Node.js version, caching, and dual publishing ([0dc9470](https://github.com/aashari/boilerplate-mcp-server/commit/0dc94705c81067d7ff63ab978ef9e6a6e3f75784))
29
- * improve package structure and add better examples ([bd66891](https://github.com/aashari/boilerplate-mcp-server/commit/bd668915bde84445161cdbd55ff9da0b0af51944))
11
+ ### Bug Fixes
12
+
13
+ * ensure executable permissions for bin script ([395f1dc](https://github.com/aashari/boilerplate-mcp-server/commit/395f1dcb5f3b5efee99048d1b91e3b083e9e544f))
14
+
15
+ # 1.0.0 (2025-03-22)
16
+
17
+ ### Bug Fixes
18
+
19
+ - add workflows permission to semantic-release workflow ([de3a335](https://github.com/aashari/boilerplate-mcp-server/commit/de3a33510bd447af353444db1fcb58e1b1aa02e4))
20
+ - improve GitHub Packages publishing with a more robust approach ([fd2aec9](https://github.com/aashari/boilerplate-mcp-server/commit/fd2aec9926cf99d301cbb2b5f5ca961a6b6fec7e))
21
+ - improve GitHub Packages publishing with better error handling and debugging ([db25f04](https://github.com/aashari/boilerplate-mcp-server/commit/db25f04925e884349fcf3ab85316550fde231d1f))
22
+ - improve GITHUB_OUTPUT syntax in semantic-release workflow ([6f154bc](https://github.com/aashari/boilerplate-mcp-server/commit/6f154bc43f42475857e9256b0a671c3263dc9708))
23
+ - improve version detection for global installations ([97a95dc](https://github.com/aashari/boilerplate-mcp-server/commit/97a95dca61d8cd7a86c81bde4cb38c509b810dc0))
24
+ - make publish workflow more resilient against version conflicts ([ffd3705](https://github.com/aashari/boilerplate-mcp-server/commit/ffd3705bc064ee9135402052a0dc7fe32645714b))
25
+ - remove invalid workflows permission ([c012e46](https://github.com/aashari/boilerplate-mcp-server/commit/c012e46a29070c8394f7ab596fe7ba68c037d3a3))
26
+ - remove type module to fix CommonJS compatibility ([8b1f00c](https://github.com/aashari/boilerplate-mcp-server/commit/8b1f00c37467bc676ad8ec9ab672ba393ed084a9))
27
+ - resolve linter errors in version detection code ([5f1f33e](https://github.com/aashari/boilerplate-mcp-server/commit/5f1f33e88ae843b7a0d708899713be36fcd2ec2e))
28
+ - update examples to use correct API (greet instead of sayHello) ([7c062ca](https://github.com/aashari/boilerplate-mcp-server/commit/7c062ca42765c659f018f990f4b1ec563d1172d3))
29
+ - update release workflow to ensure correct versioning in compiled files ([a365394](https://github.com/aashari/boilerplate-mcp-server/commit/a365394b8596defa33ff5a44583d52e2c43f0aa3))
30
+ - update version display in CLI ([2b7846c](https://github.com/aashari/boilerplate-mcp-server/commit/2b7846cbfa023f4b1a8c81ec511370fa8f5aaf33))
31
+
32
+ ### Features
30
33
 
34
+ - add automated dependency management ([efa1b62](https://github.com/aashari/boilerplate-mcp-server/commit/efa1b6292e0e9b6efd0d43b40cf7099d50769487))
35
+ - add CLI usage examples for both JavaScript and TypeScript ([d5743b0](https://github.com/aashari/boilerplate-mcp-server/commit/d5743b07a6f2afe1c6cb0b03265228cba771e657))
36
+ - add support for custom name in greet command ([be48a05](https://github.com/aashari/boilerplate-mcp-server/commit/be48a053834a1d910877864608a5e9942d913367))
37
+ - add version update script and fix version display ([ec831d3](https://github.com/aashari/boilerplate-mcp-server/commit/ec831d3a3c966d858c15972365007f9dfd6115b8))
38
+ - implement review recommendations ([a23cbc0](https://github.com/aashari/boilerplate-mcp-server/commit/a23cbc0608a07e202396b3cd496c1f2078e304c1))
39
+ - implement testing, linting, and semantic versioning ([1d7710d](https://github.com/aashari/boilerplate-mcp-server/commit/1d7710dfa11fd1cb04ba3c604e9a2eb785652394))
40
+ - improve CI workflows with standardized Node.js version, caching, and dual publishing ([0dc9470](https://github.com/aashari/boilerplate-mcp-server/commit/0dc94705c81067d7ff63ab978ef9e6a6e3f75784))
41
+ - improve package structure and add better examples ([bd66891](https://github.com/aashari/boilerplate-mcp-server/commit/bd668915bde84445161cdbd55ff9da0b0af51944))
31
42
 
32
43
  ### Reverts
33
44
 
34
- * restore simple version handling ([bd0fadf](https://github.com/aashari/boilerplate-mcp-server/commit/bd0fadfa8207b4a7cf472c3b9f4ee63d8e36189d))
45
+ - restore simple version handling ([bd0fadf](https://github.com/aashari/boilerplate-mcp-server/commit/bd0fadfa8207b4a7cf472c3b9f4ee63d8e36189d))
35
46
 
36
47
  # [1.8.0](https://github.com/aashari/boilerplate-npm-package/compare/v1.7.2...v1.8.0) (2025-03-22)
37
48
 
38
-
39
49
  ### Features
40
50
 
41
- * add CLI usage examples for both JavaScript and TypeScript ([d5743b0](https://github.com/aashari/boilerplate-npm-package/commit/d5743b07a6f2afe1c6cb0b03265228cba771e657))
51
+ - add CLI usage examples for both JavaScript and TypeScript ([d5743b0](https://github.com/aashari/boilerplate-npm-package/commit/d5743b07a6f2afe1c6cb0b03265228cba771e657))
42
52
 
43
53
  ## [1.7.2](https://github.com/aashari/boilerplate-npm-package/compare/v1.7.1...v1.7.2) (2025-03-22)
44
54
 
45
-
46
55
  ### Bug Fixes
47
56
 
48
- * update release workflow to ensure correct versioning in compiled files ([a365394](https://github.com/aashari/boilerplate-npm-package/commit/a365394b8596defa33ff5a44583d52e2c43f0aa3))
57
+ - update release workflow to ensure correct versioning in compiled files ([a365394](https://github.com/aashari/boilerplate-npm-package/commit/a365394b8596defa33ff5a44583d52e2c43f0aa3))
49
58
 
50
59
  ## [1.7.1](https://github.com/aashari/boilerplate-npm-package/compare/v1.7.0...v1.7.1) (2025-03-22)
51
60
 
52
-
53
61
  ### Bug Fixes
54
62
 
55
- * update examples to use correct API (greet instead of sayHello) ([7c062ca](https://github.com/aashari/boilerplate-npm-package/commit/7c062ca42765c659f018f990f4b1ec563d1172d3))
63
+ - update examples to use correct API (greet instead of sayHello) ([7c062ca](https://github.com/aashari/boilerplate-npm-package/commit/7c062ca42765c659f018f990f4b1ec563d1172d3))
56
64
 
57
65
  # [1.7.0](https://github.com/aashari/boilerplate-npm-package/compare/v1.6.1...v1.7.0) (2025-03-22)
58
66
 
59
-
60
67
  ### Features
61
68
 
62
- * improve package structure and add better examples ([bd66891](https://github.com/aashari/boilerplate-npm-package/commit/bd668915bde84445161cdbd55ff9da0b0af51944))
69
+ - improve package structure and add better examples ([bd66891](https://github.com/aashari/boilerplate-npm-package/commit/bd668915bde84445161cdbd55ff9da0b0af51944))
63
70
 
64
71
  ## [1.6.1](https://github.com/aashari/boilerplate-npm-package/compare/v1.6.0...v1.6.1) (2025-03-22)
65
72
 
66
-
67
73
  ### Bug Fixes
68
74
 
69
- * improve GitHub Packages publishing with better error handling and debugging ([db25f04](https://github.com/aashari/boilerplate-npm-package/commit/db25f04925e884349fcf3ab85316550fde231d1f))
75
+ - improve GitHub Packages publishing with better error handling and debugging ([db25f04](https://github.com/aashari/boilerplate-npm-package/commit/db25f04925e884349fcf3ab85316550fde231d1f))
70
76
 
71
77
  # [1.6.0](https://github.com/aashari/boilerplate-npm-package/compare/v1.5.2...v1.6.0) (2025-03-22)
72
78
 
73
-
74
79
  ### Features
75
80
 
76
- * add support for custom name in greet command ([be48a05](https://github.com/aashari/boilerplate-npm-package/commit/be48a053834a1d910877864608a5e9942d913367))
81
+ - add support for custom name in greet command ([be48a05](https://github.com/aashari/boilerplate-npm-package/commit/be48a053834a1d910877864608a5e9942d913367))
77
82
 
78
83
  ## [1.5.2](https://github.com/aashari/boilerplate-npm-package/compare/v1.5.1...v1.5.2) (2025-03-22)
79
84
 
80
-
81
85
  ### Bug Fixes
82
86
 
83
- * add workflows permission to semantic-release workflow ([de3a335](https://github.com/aashari/boilerplate-npm-package/commit/de3a33510bd447af353444db1fcb58e1b1aa02e4))
84
- * improve GITHUB_OUTPUT syntax in semantic-release workflow ([6f154bc](https://github.com/aashari/boilerplate-npm-package/commit/6f154bc43f42475857e9256b0a671c3263dc9708))
85
- * make publish workflow more resilient against version conflicts ([ffd3705](https://github.com/aashari/boilerplate-npm-package/commit/ffd3705bc064ee9135402052a0dc7fe32645714b))
86
- * remove invalid workflows permission ([c012e46](https://github.com/aashari/boilerplate-npm-package/commit/c012e46a29070c8394f7ab596fe7ba68c037d3a3))
87
+ - add workflows permission to semantic-release workflow ([de3a335](https://github.com/aashari/boilerplate-npm-package/commit/de3a33510bd447af353444db1fcb58e1b1aa02e4))
88
+ - improve GITHUB_OUTPUT syntax in semantic-release workflow ([6f154bc](https://github.com/aashari/boilerplate-npm-package/commit/6f154bc43f42475857e9256b0a671c3263dc9708))
89
+ - make publish workflow more resilient against version conflicts ([ffd3705](https://github.com/aashari/boilerplate-npm-package/commit/ffd3705bc064ee9135402052a0dc7fe32645714b))
90
+ - remove invalid workflows permission ([c012e46](https://github.com/aashari/boilerplate-npm-package/commit/c012e46a29070c8394f7ab596fe7ba68c037d3a3))
87
91
 
88
92
  ## [1.5.2](https://github.com/aashari/boilerplate-npm-package/compare/v1.5.1...v1.5.2) (2025-03-22)
89
93
 
90
-
91
94
  ### Bug Fixes
92
95
 
93
- * make publish workflow more resilient against version conflicts ([ffd3705](https://github.com/aashari/boilerplate-npm-package/commit/ffd3705bc064ee9135402052a0dc7fe32645714b))
96
+ - make publish workflow more resilient against version conflicts ([ffd3705](https://github.com/aashari/boilerplate-npm-package/commit/ffd3705bc064ee9135402052a0dc7fe32645714b))
94
97
 
95
98
  ## [1.5.1](https://github.com/aashari/boilerplate-npm-package/compare/v1.5.0...v1.5.1) (2025-03-22)
96
99
 
97
-
98
100
  ### Bug Fixes
99
101
 
100
- * improve GitHub Packages publishing with a more robust approach ([fd2aec9](https://github.com/aashari/boilerplate-npm-package/commit/fd2aec9926cf99d301cbb2b5f5ca961a6b6fec7e))
102
+ - improve GitHub Packages publishing with a more robust approach ([fd2aec9](https://github.com/aashari/boilerplate-npm-package/commit/fd2aec9926cf99d301cbb2b5f5ca961a6b6fec7e))
101
103
 
102
104
  # [1.5.0](https://github.com/aashari/boilerplate-npm-package/compare/v1.4.7...v1.5.0) (2025-03-22)
103
105
 
104
-
105
106
  ### Features
106
107
 
107
- * improve CI workflows with standardized Node.js version, caching, and dual publishing ([0dc9470](https://github.com/aashari/boilerplate-npm-package/commit/0dc94705c81067d7ff63ab978ef9e6a6e3f75784))
108
+ - improve CI workflows with standardized Node.js version, caching, and dual publishing ([0dc9470](https://github.com/aashari/boilerplate-npm-package/commit/0dc94705c81067d7ff63ab978ef9e6a6e3f75784))
package/README.md CHANGED
@@ -1,146 +1,12 @@
1
1
  # Boilerplate MCP Server
2
2
 
3
- A boilerplate Model Context Protocol (MCP) server implementation using TypeScript. This project demonstrates how to build a well-structured MCP server that exposes both tools and resources to AI applications like Claude Desktop. It serves as a starting point for developers building MCP-compatible servers with a focus on clean architecture, automated workflows, and easy deployment.
4
-
5
- ## Core Features
6
-
7
- - **STDIO MCP Server**: Designed for AI clients like Claude Desktop, providing tools and resources via the Model Context Protocol.
8
- - **CLI Support**: Human-friendly command-line interface for the same functionality, making it easy to test and use directly.
9
- - **IP Address Lookup**: Get details about any IP address or your current device's IP.
10
- - **Flexible Configuration**: Support for environment variables, .env files, and global config files.
11
- - **Testing & Development Tools**: Built-in inspection, testing, and development utilities.
12
-
13
- ## Installation
14
-
15
- ### Global Installation
16
-
17
- You can install this package globally to use as a CLI tool:
18
-
19
- ```bash
20
- npm install -g @aashari/boilerplate-mcp-server
21
- ```
22
-
23
- After global installation, you can run the CLI commands directly:
24
-
25
- ```bash
26
- # Get help
27
- mcp-server --help
28
-
29
- # Get current IP details
30
- mcp-server get-ip-details
31
-
32
- # Get details for a specific IP
33
- mcp-server get-ip-details 8.8.8.8
34
- ```
35
-
36
- ### Local Installation
37
-
38
- For development or local use, clone the repository and install dependencies:
39
-
40
- ```bash
41
- git clone https://github.com/aashari/boilerplate-mcp-server.git
42
- cd boilerplate-mcp-server
43
- npm install
44
- ```
45
-
46
- Then run the development server:
47
-
48
- ```bash
49
- npm run dev
50
- ```
51
-
52
- Or build and start:
53
-
54
- ```bash
55
- npm run build
56
- npm start
57
- ```
58
-
59
- ## Developer Tools
60
-
61
- This project includes several scripts to make development easier:
62
-
63
- ```bash
64
- # Run tests
65
- npm test
66
-
67
- # Check test coverage
68
- npm run test:coverage
69
-
70
- # Run linting
71
- npm run lint
72
-
73
- # Format code
74
- npm run format
75
-
76
- # Run the server with live reload during development
77
- npm run dev
78
-
79
- # Use the MCP Inspector to visually test your server
80
- npm run inspect
81
-
82
- # Use the MCP Inspector with debug mode enabled
83
- npm run inspect:debug
84
- ```
85
-
86
- ## Configuration Options for End Users
87
-
88
- Before setting up with Claude Desktop or Cursor AI, you can configure the server. There are two recommended options for end users:
89
-
90
- ### Option 1: Direct Configuration in Claude/Cursor
91
-
92
- Pass your configuration directly in the Claude Desktop config or Cursor AI command:
93
-
94
- ```json
95
- {
96
- "mcpServers": {
97
- "aashari/boilerplate-mcp-server": {
98
- "command": "npx",
99
- "args": [
100
- "-y",
101
- "DEBUG=true",
102
- "IPAPI_API_TOKEN=your_token",
103
- "@aashari/boilerplate-mcp-server"
104
- ]
105
- }
106
- }
107
- }
108
- ```
109
-
110
- ### Option 2: Global Configuration File (Recommended)
111
-
112
- 1. Create a global configuration file at `$HOME/.mcp/configs.json`:
113
-
114
- ```json
115
- {
116
- "@aashari/boilerplate-mcp-server": {
117
- "environments": {
118
- "DEBUG": "true",
119
- "IPAPI_API_TOKEN": "your_token"
120
- }
121
- }
122
- }
123
- ```
124
-
125
- 2. Then use a simplified configuration in Claude Desktop or Cursor AI:
126
-
127
- ```json
128
- {
129
- "mcpServers": {
130
- "aashari/boilerplate-mcp-server": {
131
- "command": "npx",
132
- "args": ["-y", "@aashari/boilerplate-mcp-server"]
133
- }
134
- }
135
- }
136
- ```
3
+ ## About MCP
137
4
 
138
- This approach keeps your configuration in one secure location and simplifies your AI assistant setup.
5
+ The Model Context Protocol (MCP) is an open standard developed by Anthropic to simplify how AI systems connect to external data sources and tools. This boilerplate implementation provides a starting point for creating MCP servers that can be used with Claude Desktop and other MCP-compatible AI systems.
139
6
 
140
- ### Available Configuration Options
7
+ ## Overview
141
8
 
142
- - **DEBUG**: Set to `true` to enable debug logging.
143
- - **IPAPI_API_TOKEN**: API token for the IP API service (if required).
9
+ A TypeScript-based Model Context Protocol (MCP) server boilerplate for building AI-connected tools. Features IP lookup tools, CLI support, MCP Inspector integration, and extensible architecture for connecting Claude/Anthropic AI systems to external data sources.
144
10
 
145
11
  ## Setting Up with Claude Desktop
146
12
 
@@ -158,7 +24,7 @@ To use this MCP server with Claude Desktop:
158
24
 
159
25
  3. **Update Configuration File**:
160
26
 
161
- - Add one of the configuration options from above to the file
27
+ - Add one of the configuration options from below to the file
162
28
  - Save the file
163
29
 
164
30
  Example with global configuration file already set up:
@@ -185,7 +51,6 @@ To use this MCP server with Claude Desktop:
185
51
  - Ensure the `get-ip-details` tool is listed
186
52
 
187
53
  6. **Test the Tool**:
188
-
189
54
  - Try asking Claude: "give me my public IP" or "analyze this IP: 8.8.8.8"
190
55
  - Claude will use the MCP tool to fetch and display the requested information
191
56
 
@@ -231,86 +96,101 @@ To use this MCP server with Cursor AI:
231
96
  - You should see the `get_ip_details` tool listed under the server
232
97
 
233
98
  5. **Test the Tool**:
234
-
235
99
  - In the chat sidebar, ensure Agent mode is active
236
100
  - Try asking: "give me my public IP" or "analyze this IP: 8.8.8.8"
237
101
  - Cursor AI will use the MCP tool to fetch and display the requested information
238
102
 
239
103
  ## Using as a CLI Tool
240
104
 
241
- The package can also be used as a command-line tool for human interaction:
105
+ This package can also be used as a command-line tool:
242
106
 
243
- - **Get help and available commands**:
107
+ ### Global Installation
244
108
 
245
- ```bash
246
- npx -y @aashari/boilerplate-mcp-server --help
247
- ```
109
+ You can install this package globally to use as a CLI tool:
248
110
 
249
- Example output:
111
+ ```bash
112
+ npm install -g @aashari/boilerplate-mcp-server
113
+ ```
250
114
 
251
- ```
252
- Usage: @aashari/boilerplate-mcp-server [options] [command]
115
+ After global installation, you can run the CLI commands directly:
253
116
 
254
- A boilerplate Model Context Protocol (MCP) server implementation using TypeScript
117
+ ```bash
118
+ # Get help
119
+ mcp-server --help
255
120
 
256
- Options:
257
- -V, --version output the version number
258
- -h, --help display help for command
121
+ # Get current IP details
122
+ mcp-server get-ip-details
259
123
 
260
- Commands:
261
- get-ip-details [ipAddress] Get details about a specific IP address or the current device
262
- help [command] display help for command
263
- ```
124
+ # Get details for a specific IP
125
+ mcp-server get-ip-details 8.8.8.8
126
+ ```
264
127
 
265
- - **Get current device IP details**:
128
+ ## Configuration Options for End Users
266
129
 
267
- ```bash
268
- npx -y @aashari/boilerplate-mcp-server get-ip-details
269
- ```
130
+ Before setting up with Claude Desktop or Cursor AI, you can configure the server. There are two recommended options for end users:
270
131
 
271
- Example output:
132
+ ### Option 1: Direct Configuration in Claude/Cursor
272
133
 
273
- ```
274
- status: success
275
- country: Indonesia
276
- countryCode: ID
277
- region: JK
278
- regionName: Jakarta
279
- city: Jakarta
280
- zip: 11730
281
- lat: -6.2114
282
- lon: 106.8446
283
- timezone: Asia/Jakarta
284
- isp: Biznet Wifi
285
- org:
286
- as: AS17451 BIZNET NETWORKS
287
- query: 118.99.106.135
288
- ```
134
+ Pass your configuration directly in the Claude Desktop config or Cursor AI command:
289
135
 
290
- - **Get details for a specific IP address**:
136
+ ```json
137
+ {
138
+ "mcpServers": {
139
+ "aashari/boilerplate-mcp-server": {
140
+ "command": "npx",
141
+ "args": [
142
+ "-y",
143
+ "DEBUG=true",
144
+ "IPAPI_API_TOKEN=your_token",
145
+ "@aashari/boilerplate-mcp-server"
146
+ ]
147
+ }
148
+ }
149
+ }
150
+ ```
291
151
 
292
- ```bash
293
- npx -y @aashari/boilerplate-mcp-server get-ip-details 8.8.8.8
294
- ```
152
+ ### Option 2: Global Configuration File (Recommended)
295
153
 
296
- Example output:
154
+ 1. Create a global configuration file at `$HOME/.mcp/configs.json`:
297
155
 
298
- ```
299
- status: success
300
- country: United States
301
- countryCode: US
302
- region: VA
303
- regionName: Virginia
304
- city: Ashburn
305
- zip: 20149
306
- lat: 39.03
307
- lon: -77.5
308
- timezone: America/New_York
309
- isp: Google LLC
310
- org: Google Public DNS
311
- as: AS15169 Google LLC
312
- query: 8.8.8.8
313
- ```
156
+ ```json
157
+ {
158
+ "@aashari/boilerplate-mcp-server": {
159
+ "environments": {
160
+ "DEBUG": "true",
161
+ "IPAPI_API_TOKEN": "your_token"
162
+ }
163
+ }
164
+ }
165
+ ```
166
+
167
+ 2. Then use a simplified configuration in Claude Desktop or Cursor AI:
168
+
169
+ ```json
170
+ {
171
+ "mcpServers": {
172
+ "aashari/boilerplate-mcp-server": {
173
+ "command": "npx",
174
+ "args": ["-y", "@aashari/boilerplate-mcp-server"]
175
+ }
176
+ }
177
+ }
178
+ ```
179
+
180
+ This approach keeps your configuration in one secure location and simplifies your AI assistant setup.
181
+
182
+ ### Available Configuration Options
183
+
184
+ - **DEBUG**: Set to `true` to enable debug logging.
185
+ - **IPAPI_API_TOKEN**: API token for the IP API service (if required).
186
+
187
+ ## Core Features
188
+
189
+ - **STDIO MCP Server**: Designed for AI clients like Claude Desktop, providing tools and resources via the Model Context Protocol.
190
+ - **CLI Support**: Human-friendly command-line interface for the same functionality, making it easy to test and use directly.
191
+ - **IP Address Lookup**: Get details about any IP address or your current device's IP.
192
+ - **Flexible Configuration**: Support for environment variables, .env files, and global config files.
193
+ - **Testing & Development Tools**: Built-in inspection, testing, and development utilities.
314
194
 
315
195
  ## For Developers
316
196
 
@@ -338,10 +218,6 @@ The inspector provides a visual way to see:
338
218
  - The requests and responses between client and server
339
219
  - Any errors that occur during communication
340
220
 
341
- ## About MCP
342
-
343
- The Model Context Protocol (MCP) is an open standard developed by Anthropic to simplify how AI systems connect to external data sources and tools. For detailed information, including core concepts, architecture, and implementation guides, please refer to the [official MCP documentation](https://modelcontextprotocol.io/docs/).
344
-
345
221
  ## Extending This Project
346
222
 
347
223
  To add your own tools and resources:
@@ -352,6 +228,33 @@ To add your own tools and resources:
352
228
  4. Create resource implementations in `src/resources`
353
229
  5. Register your new tools and resources in `src/index.ts`
354
230
 
231
+ ## Developer Tools
232
+
233
+ This project includes several scripts to make development easier:
234
+
235
+ ```bash
236
+ # Run tests
237
+ npm test
238
+
239
+ # Check test coverage
240
+ npm run test:coverage
241
+
242
+ # Run linting
243
+ npm run lint
244
+
245
+ # Format code
246
+ npm run format
247
+
248
+ # Run the server with live reload during development
249
+ npm run dev
250
+
251
+ # Use the MCP Inspector to visually test your server
252
+ npm run inspect
253
+
254
+ # Use the MCP Inspector with debug mode enabled
255
+ npm run inspect:debug
256
+ ```
257
+
355
258
  ## License
356
259
 
357
260
  [ISC](https://opensource.org/licenses/ISC)
package/dist/cli/index.js CHANGED
@@ -8,7 +8,7 @@ const commander_1 = require("commander");
8
8
  const logger_util_js_1 = require("../utils/logger.util.js");
9
9
  const ipaddress_cli_js_1 = __importDefault(require("./ipaddress.cli.js"));
10
10
  // Get the version from package.json
11
- const VERSION = '1.0.0'; // This should match the version in src/index.ts
11
+ const VERSION = '1.0.2'; // This should match the version in src/index.ts
12
12
  const NAME = '@aashari/boilerplate-mcp-server';
13
13
  const DESCRIPTION = 'A boilerplate Model Context Protocol (MCP) server implementation using TypeScript';
14
14
  async function runCli(args) {
package/dist/cli/index.js.bak CHANGED
@@ -8,7 +8,7 @@ const commander_1 = require("commander");
8
8
  const logger_util_js_1 = require("../utils/logger.util.js");
9
9
  const ipaddress_cli_js_1 = __importDefault(require("./ipaddress.cli.js"));
10
10
  // Get the version from package.json
11
- const VERSION = '1.1.0'; // This should match the version in src/index.ts
11
+ const VERSION = '1.0.1'; // This should match the version in src/index.ts
12
12
  const NAME = '@aashari/boilerplate-mcp-server';
13
13
  const DESCRIPTION = 'A boilerplate Model Context Protocol (MCP) server implementation using TypeScript';
14
14
  async function runCli(args) {
package/dist/index.js CHANGED
@@ -30,6 +30,8 @@ const error_util_js_1 = require("./utils/error.util.js");
30
30
  const index_js_1 = require("./cli/index.js");
31
31
  const ipaddress_tool_js_1 = __importDefault(require("./tools/ipaddress.tool.js"));
32
32
  const ipaddress_resource_js_1 = __importDefault(require("./resources/ipaddress.resource.js"));
33
+ // Define version constant for easier management and consistent versioning
34
+ const VERSION = '1.0.2';
33
35
  let serverInstance = null;
34
36
  let transportInstance = null;
35
37
  async function startServer(mode = 'stdio') {
@@ -45,7 +47,7 @@ async function startServer(mode = 'stdio') {
45
47
  logger_util_js_1.logger.info(`[src/index.ts] Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
46
48
  serverInstance = new mcp_js_1.McpServer({
47
49
  name: '@aashari/boilerplate-mcp-server',
48
- version: '1.0.0',
50
+ version: VERSION,
49
51
  });
50
52
  if (mode === 'stdio') {
51
53
  transportInstance = new stdio_js_1.StdioServerTransport();
package/dist/index.js.bak CHANGED
@@ -30,6 +30,8 @@ const error_util_js_1 = require("./utils/error.util.js");
30
30
  const index_js_1 = require("./cli/index.js");
31
31
  const ipaddress_tool_js_1 = __importDefault(require("./tools/ipaddress.tool.js"));
32
32
  const ipaddress_resource_js_1 = __importDefault(require("./resources/ipaddress.resource.js"));
33
+ // Define version constant for easier management and consistent versioning
34
+ const VERSION = '1.0.1';
33
35
  let serverInstance = null;
34
36
  let transportInstance = null;
35
37
  async function startServer(mode = 'stdio') {
@@ -45,7 +47,7 @@ async function startServer(mode = 'stdio') {
45
47
  logger_util_js_1.logger.info(`[src/index.ts] Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
46
48
  serverInstance = new mcp_js_1.McpServer({
47
49
  name: '@aashari/boilerplate-mcp-server',
48
- version: '1.1.0',
50
+ version: VERSION,
49
51
  });
50
52
  if (mode === 'stdio') {
51
53
  transportInstance = new stdio_js_1.StdioServerTransport();
package/dist/tools/ipaddress.tool.js CHANGED
@@ -22,7 +22,7 @@ async function getIpAddressDetails(args, _extra) {
22
22
  };
23
23
  }
24
24
  catch (error) {
25
- logger_util_js_1.logger.error(`[src/tools/ipaddress.tool.ts@getIpAddressDetails] Error getting IP details`, error);
25
+ logger_util_js_1.logger.error(`[src/tools/ipaddress.tool.ts@getIpAddressDetails] Error getting details for IP: ${args.ipAddress || 'current IP'}`, error);
26
26
  return (0, error_util_js_1.formatErrorForMcpTool)(error);
27
27
  }
28
28
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aashari/boilerplate-mcp-server",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "A TypeScript-based Model Context Protocol (MCP) server boilerplate for building AI-connected tools. Features IP lookup tools, CLI support, MCP Inspector integration, and extensible architecture for connecting Claude/Anthropic AI systems to external data sources.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -14,6 +14,8 @@
14
14
  },
15
15
  "scripts": {
16
16
  "build": "tsc",
17
+ "prepare": "npm run build && chmod +x dist/index.js",
18
+ "postinstall": "chmod +x dist/index.js || true",
17
19
  "test": "jest",
18
20
  "test:coverage": "jest --coverage",
19
21
  "lint": "eslint src --ext .ts --config eslint.config.mjs",
@@ -84,5 +86,49 @@
84
86
  },
85
87
  "directories": {
86
88
  "example": "examples"
89
+ },
90
+ "jest": {
91
+ "preset": "ts-jest",
92
+ "testEnvironment": "node",
93
+ "testMatch": [
94
+ "**/src/**/*.test.ts"
95
+ ],
96
+ "collectCoverageFrom": [
97
+ "src/**/*.ts",
98
+ "!src/**/*.test.ts",
99
+ "!src/**/*.spec.ts"
100
+ ],
101
+ "coveragePathIgnorePatterns": [
102
+ "/node_modules/",
103
+ "/dist/",
104
+ "/coverage/"
105
+ ],
106
+ "coverageReporters": [
107
+ "text",
108
+ "lcov",
109
+ "json-summary"
110
+ ],
111
+ "transform": {
112
+ "^.+\\.tsx?$": [
113
+ "ts-jest",
114
+ {
115
+ "useESM": true
116
+ }
117
+ ]
118
+ },
119
+ "moduleNameMapper": {
120
+ "(.*)\\.(js|jsx)$": "$1"
121
+ },
122
+ "extensionsToTreatAsEsm": [
123
+ ".ts"
124
+ ],
125
+ "moduleFileExtensions": [
126
+ "ts",
127
+ "tsx",
128
+ "js",
129
+ "jsx",
130
+ "json",
131
+ "node"
132
+ ]
87
133
  }
88
134
  }
package/package.json.bak CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aashari/boilerplate-mcp-server",
3
- "version": "1.1.0",
3
+ "version": "1.0.1",
4
4
  "description": "A TypeScript-based Model Context Protocol (MCP) server boilerplate for building AI-connected tools. Features IP lookup tools, CLI support, MCP Inspector integration, and extensible architecture for connecting Claude/Anthropic AI systems to external data sources.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -14,6 +14,8 @@
14
14
  },
15
15
  "scripts": {
16
16
  "build": "tsc",
17
+ "prepare": "npm run build && chmod +x dist/index.js",
18
+ "postinstall": "chmod +x dist/index.js || true",
17
19
  "test": "jest",
18
20
  "test:coverage": "jest --coverage",
19
21
  "lint": "eslint src --ext .ts --config eslint.config.mjs",
@@ -84,5 +86,49 @@
84
86
  },
85
87
  "directories": {
86
88
  "example": "examples"
89
+ },
90
+ "jest": {
91
+ "preset": "ts-jest",
92
+ "testEnvironment": "node",
93
+ "testMatch": [
94
+ "**/src/**/*.test.ts"
95
+ ],
96
+ "collectCoverageFrom": [
97
+ "src/**/*.ts",
98
+ "!src/**/*.test.ts",
99
+ "!src/**/*.spec.ts"
100
+ ],
101
+ "coveragePathIgnorePatterns": [
102
+ "/node_modules/",
103
+ "/dist/",
104
+ "/coverage/"
105
+ ],
106
+ "coverageReporters": [
107
+ "text",
108
+ "lcov",
109
+ "json-summary"
110
+ ],
111
+ "transform": {
112
+ "^.+\\.tsx?$": [
113
+ "ts-jest",
114
+ {
115
+ "useESM": true
116
+ }
117
+ ]
118
+ },
119
+ "moduleNameMapper": {
120
+ "(.*)\\.(js|jsx)$": "$1"
121
+ },
122
+ "extensionsToTreatAsEsm": [
123
+ ".ts"
124
+ ],
125
+ "moduleFileExtensions": [
126
+ "ts",
127
+ "tsx",
128
+ "js",
129
+ "jsx",
130
+ "json",
131
+ "node"
132
+ ]
87
133
  }
88
134
  }
package/scripts/update-version.js CHANGED
@@ -52,7 +52,7 @@ const versionFiles = [
52
52
  },
53
53
  {
54
54
  path: path.join(rootDir, 'src', 'index.ts'),
55
- pattern: /version: ['"]([^'"]*)['"]/,
55
+ pattern: /const VERSION = ['"]([^'"]*)['"]/,
56
56
  replacement: (match, currentVersion) =>
57
57
  match.replace(currentVersion, newVersion),
58
58
  },
@@ -62,12 +62,14 @@ const versionFiles = [
62
62
  pattern: /const VERSION = ['"]([^'"]*)['"]/,
63
63
  replacement: (match, currentVersion) =>
64
64
  match.replace(currentVersion, newVersion),
65
+ optional: true, // Mark this file as optional
65
66
  },
66
67
  {
67
68
  path: path.join(rootDir, 'dist', 'index.js'),
68
- pattern: /version: ['"]([^'"]*)['"]/,
69
+ pattern: /const VERSION = ['"]([^'"]*)['"]/,
69
70
  replacement: (match, currentVersion) =>
70
71
  match.replace(currentVersion, newVersion),
72
+ optional: true, // Mark this file as optional
71
73
  },
72
74
  // Additional files can be added here with their patterns and replacement logic
73
75
  ];
@@ -120,12 +122,21 @@ function validateVersion(version) {
120
122
  * @param {Object} fileConfig - Configuration for the file to update
121
123
  */
122
124
  function updateFileVersion(fileConfig) {
123
- const { path: filePath, pattern, replacement } = fileConfig;
125
+ const {
126
+ path: filePath,
127
+ pattern,
128
+ replacement,
129
+ optional = false,
130
+ } = fileConfig;
124
131
 
125
132
  try {
126
133
  log(`Checking ${filePath}...`, true);
127
134
 
128
135
  if (!fs.existsSync(filePath)) {
136
+ if (optional) {
137
+ log(`Optional file not found (skipping): ${filePath}`, true);
138
+ return;
139
+ }
129
140
  console.warn(`Warning: File not found: ${filePath}`);
130
141
  return;
131
142
  }
@@ -168,6 +179,10 @@ function updateFileVersion(fileConfig) {
168
179
  );
169
180
  }
170
181
  } catch (error) {
182
+ if (optional) {
183
+ log(`Error with optional file ${filePath}: ${error.message}`, true);
184
+ return;
185
+ }
171
186
  console.error(`Error updating ${filePath}: ${error.message}`);
172
187
  process.exit(1);
173
188
  }
package/jest.config.mjs DELETED
@@ -1,19 +0,0 @@
1
- /** @type {import('ts-jest').JestConfigWithTsJest} */
2
- export default {
3
- preset: 'ts-jest',
4
- testEnvironment: 'node',
5
- testMatch: ['**/src/**/*.test.ts'],
6
- transform: {
7
- '^.+\\.tsx?$': [
8
- 'ts-jest',
9
- {
10
- useESM: true,
11
- },
12
- ],
13
- },
14
- moduleNameMapper: {
15
- '(.*)\\.(js|jsx)$': '$1',
16
- },
17
- extensionsToTreatAsEsm: ['.ts'],
18
- moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
19
- };