Skip to content

Commit 8d07f5c

Browse files
theodorosploumistheodorosploumis
committed
The mcp npm package shows the wrong README
1 parent f36c1c0 commit 8d07f5c

File tree

3 files changed

+290
-52
lines changed

3 files changed

+290
-52
lines changed

‎mcp-package/build.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ writeFileSync(serverDest, serverContent);
5959
console.log('✓ Copied server to dist/');
6060

6161
// Copy README
62-
const readmeSrc = join(rootDir, 'README.md');
62+
const readmeSrc = join(__dirname, 'README.md');
6363
const readmeDest = join(distDir, 'README.md');
6464
if (existsSync(readmeSrc)) {
6565
const readmeContent = readFileSync(readmeSrc, 'utf8');

‎mcp-package/dist/README.md‎

Lines changed: 274 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,295 @@
1-
<img src="img/logo.png" align="left" alt="Drupaltools logo">
1+
# @drupaltools/mcp
22

3-
# DrupalTools
3+
A Model Context Protocol (MCP) server for discovering Drupal development tools, utilities, and projects. This MCP server provides intelligent search and categorization of 186+ Drupal tools to help developers find the right tools for their needs.
44

5-
Project [drupaltools.github.io](https://drupaltools.github.io/), a list of open-source tools used for
6-
Drupal development and other Drupal related tasks.
5+
## Installation
76

8-
## Contributing
7+
### Using npx (Recommended)
8+
9+
No installation required! Just add to your Claude Desktop configuration:
910

10-
Missing a tool here? Just fork the repo and add your tool as a `<name>.yml` in the `_data/projects` folder.
11-
12-
```yaml
13-
# _data/projects/example-tool.yml
14-
name: Example Tool
15-
year_created: 2024
16-
source: https://github.com/example/example-tool
17-
homepage: https://example.com
18-
description: |
19-
A single sentence that will appear in the listings.
20-
requires:
21-
- php
22-
drupal_versions:
23-
- 10
24-
category:
25-
- devops
26-
recommended: true
11+
```json
12+
{
13+
"mcpServers": {
14+
"drupaltools": {
15+
"type": "stdio",
16+
"command": "npx",
17+
"args": ["@drupaltools/mcp@latest"]
18+
}
19+
}
20+
}
2721
```
2822

29-
Use the same keys shown above so the site build picks up the metadata correctly.
30-
Optional keys such as `docs`, `logo`, or `similar` can be added when the information is available.
23+
### Global Install
3124

32-
Make sure to follow the following rules:
25+
```bash
26+
npm install -g @drupaltools/mcp
27+
```
3328

34-
- **Open Source:** The tool must have a public repository on Github, Gitlab, Bitbucket etc that we can link to and pull in stats from.
35-
- **Stick to the format:** Fill out all the same fields as the other tools in `_data/projects`.
36-
- **Short description:** Keep all the details for the body text, keep the description for the overview page short and sweet.
37-
- Respect the **[Code of Conduct](blob/master/CODE_OF_CONDUCT.md)**.
29+
Then add to Claude Desktop configuration:
3830

39-
## Running locally
31+
```json
32+
{
33+
"mcpServers": {
34+
"drupaltools": {
35+
"type": "stdio",
36+
"command": "drupaltools-mcp"
37+
}
38+
}
39+
}
40+
```
4041

41-
Drupaltools is built with Jekyll, Bundler and Liquid. To install and run locally:
42+
## Available Tools
43+
44+
### 1. `list_tools`
45+
List all available Drupal tools with optional filtering.
46+
47+
**Parameters:**
48+
- `category` (optional): Filter by category (e.g., 'testing', 'cli', 'deployment')
49+
- `limit` (optional, default: 50): Maximum number of tools to return
50+
51+
**Example:**
52+
```javascript
53+
{
54+
"name": "list_tools",
55+
"arguments": {
56+
"category": "testing",
57+
"limit": 10
58+
}
59+
}
60+
```
61+
62+
### 2. `search_tools`
63+
Search for tools using intelligent semantic matching.
64+
65+
**Scoring:**
66+
- Title matches: 100 points
67+
- Category matches: 50 points
68+
- Tag matches: 30 points
69+
- Description matches: 20 points
70+
- Homepage/source matches: 10 points
71+
72+
**Parameters:**
73+
- `query` (required): Search query
74+
- `limit` (optional, default: 10): Maximum results to return
75+
76+
**Example:**
77+
```javascript
78+
{
79+
"name": "search_tools",
80+
"arguments": {
81+
"query": "docker",
82+
"limit": 5
83+
}
84+
}
85+
```
86+
87+
### 3. `get_tool`
88+
Get detailed information about a specific tool.
89+
90+
**Parameters:**
91+
- `tool_id` (required): The tool ID or tool name
92+
93+
**Example:**
94+
```javascript
95+
{
96+
"name": "get_tool",
97+
"arguments": {
98+
"tool_id": "blt"
99+
}
100+
}
101+
```
102+
103+
## Categories
104+
105+
Tools are categorized into:
106+
- **cli**: Command-line tools and utilities
107+
- **testing**: Testing frameworks and utilities
108+
- **deployment**: Deployment and automation tools
109+
- **development**: Development aids and utilities
110+
- **debug**: Debugging and analysis tools
111+
- **ci**: Continuous integration tools
112+
- **performance**: Performance optimization tools
113+
- **security**: Security scanning and analysis
114+
- **monitoring**: Monitoring and logging tools
115+
- **migration**: Migration and data import/export tools
116+
117+
## Example Usage in Claude Desktop
118+
119+
Once configured, you can ask Claude to:
120+
121+
> "Show me 5 tools for testing Drupal sites"
122+
123+
> "Search for Docker-based Drupal development tools"
124+
125+
> "Tell me about BLT (Acquia Lightning) tool"
126+
127+
> "List all CLI tools for Drupal"
128+
129+
## Data Source
130+
131+
This MCP server contains data for 160+ Drupal tools sourced from the Drupal Tools community project (https://drupaltools.github.io).
132+
The data is embedded in the package, so it works offline and doesn't require external API calls.
133+
134+
## Development
42135

43136
```bash
44-
gem install jekyll bundler
45-
git clone https://github.com/theodorosploumis/drupaltools.git
46-
cd drupaltools
47-
bundle install
48-
bundle exec jekyll serve
137+
git clone https://github.com/drupaltools/drupaltools.github.io
138+
cd drupaltools.github.io/mcp-package
139+
npm install
140+
npm run mcp
49141
```
50142

51-
## MCP Server
143+
The server is built using the **JavaScript/TypeScript MCP SDK** (`@modelcontextprotocol/sdk` v1.24.3) with ES modules.
144+
145+
### Key Architecture Decisions:
146+
- **Language**: Pure JavaScript with ES modules (no TypeScript compilation)
147+
- **Transport**: Stdio for easy integration with Claude Desktop
148+
- **Data Loading**: Asynchronous loading with lazy initialization
149+
- **Scoring**: Deterministic scoring algorithm for search relevance
150+
- **Error Handling**: Graceful fallbacks (ID lookup → name lookup)
151+
152+
### Architecture:
153+
```
154+
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
155+
│ YAML Files │────▶│ Load Project │────▶│ Indexed Data │
156+
│ (_data/projects)│ │ Data │ │ (Map) │
157+
└─────────────────┘ └──────────────────┘ └─────────────────┘
158+
│
159+
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
160+
│ MCP Client │────▶│ Tool Handlers │────▶│ Search/Filter │
161+
│ (any AI tool) │ │ (list/search/get)│ │ Logic │
162+
└─────────────────┘ └──────────────────┘ └─────────────────┘
163+
```
52164

53-
- [mcp-package/README.md](./mcp-package/README.md)
54-
- [mcp-server/README.md](./mcp-server/README.md)
165+
Key features:
55166

56-
## Similar tools
167+
- Static content only - no external APIs
168+
- Read-only operations
169+
- Minimal latency and cost
170+
- Automatic indexing on startup (186+ tools)
171+
- Deterministic tool suggestions
172+
- Smart semantic search with field-weighted scoring
173+
174+
## Publishing
175+
176+
### Required GitHub Repository Secrets
177+
178+
To enable automated publishing, you need to set up the following secrets in your GitHub repository:
179+
180+
1. **NPM_TOKEN** (Required for npm publishing)
181+
- Go to: https://www.npmjs.com
182+
- Create an account or log in
183+
- Generate an access token: Account Settings → Access Tokens → Generate New Token
184+
- Set the token with automation permissions
185+
- Add to GitHub: Repository Settings → Secrets and variables → Actions → New repository secret
186+
- Name: `NPM_TOKEN`
187+
- Value: Your npm access token
188+
189+
2. **GITHUB_TOKEN** (Already provided by GitHub Actions)
190+
- This is automatically available in workflows with `permissions: contents: write`
191+
192+
### Package Name
193+
194+
**Package Name:** `@drupaltools/mcp`
195+
196+
This is the name you'll use to install the package:
197+
```bash
198+
npx @drupaltools/mcp
199+
```
200+
201+
### Manual Publishing
202+
203+
From the project root:
204+
205+
```bash
206+
cd mcp-package
207+
npm run publish
208+
```
209+
210+
Or run the steps individually:
211+
212+
```bash
213+
cd mcp-package
214+
npm run build
215+
npm test
216+
npm run publish:npm
217+
```
218+
219+
### Automated Publishing via GitHub Actions
220+
221+
#### Option 1: Tag-based Publishing (Recommended)
222+
1. Create and push a version tag:
223+
```bash
224+
git tag v1.0.0
225+
git push origin v1.0.0
226+
```
227+
This will automatically trigger the publish workflow
228+
229+
#### Option 2: Manual Trigger
230+
1. Go to: Repository → Actions → "Publish to npm"
231+
2. Click "Run workflow"
232+
3. Enter the version number (e.g., "1.0.0")
233+
4. Click "Run workflow"
234+
235+
#### What the workflow does:
236+
- ✅ Builds the MCP package with latest data
237+
- ✅ Runs tests to ensure everything works
238+
- ✅ Publishes to npm registry
239+
- ✅ Creates a GitHub release
240+
- ✅ Updates version numbers in package.json files
241+
242+
### Publishing for the First Time
243+
244+
1. **Set up npm account** (if you don't have one):
245+
- Visit https://www.npmjs.com
246+
- Click "Sign up"
247+
- Verify your email address
248+
249+
2. **Generate npm token**:
250+
- Log in to npm
251+
- Go to Account Settings → Access Tokens
252+
- Click "Generate New Token"
253+
- Name: `drupaltools-mcp` (or any descriptive name)
254+
- Select permissions: "Automation"
255+
- Click "Generate Token"
256+
- **Important**: Copy the token immediately (you won't see it again)
257+
258+
3. **Add token to GitHub**:
259+
- Go to your GitHub repository
260+
- Settings → Secrets and variables → Actions
261+
- Click "New repository secret"
262+
- Name: `NPM_TOKEN`
263+
- Value: Paste your npm token
264+
- Click "Add secret"
265+
266+
4. **Publish the package**:
267+
```bash
268+
cd mcp-package
269+
npm publish
270+
```
271+
272+
### Post-Publishing Verification
273+
274+
After publishing, verify the package:
275+
1. Visit https://www.npmjs.com/package/@drupaltools/mcp
276+
2. Test installation:
277+
```bash
278+
npx @drupaltools/mcp@latest --version
279+
```
280+
3. The package should be publicly available for anyone to use
281+
282+
## Contributing
57283

58-
See also:
284+
To add or update tools:
59285

60-
- https://jakzal.github.io/toolbox
286+
1. Visit https://github.com/drupaltools/drupaltools.github.io
287+
2. Edit or add YAML files in the `_data/projects/` directory
288+
3. Submit a pull request
61289

62-
## License
290+
The MCP package will be automatically updated when changes are merged (if the workflow is triggered).
63291

64-
This project is licensed under the [MIT license](LICENSE.md).
292+
## Support
65293

66-
[Drupal](https://www.drupal.org) is a [registered trademark](http://drupal.com/trademark) of [Dries Buytaert](http://buytaert.net/).
294+
- Issues: https://github.com/drupaltools/drupaltools.github.io/issues
295+
- Documentation: https://drupaltools.github.io

‎mcp-package/dist/package.json‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@drupaltools/mcp",
3-
"version": "1.1.0",
3+
"version": "1.0.7",
44
"description": "Model Context Protocol (MCP) server for discovering Drupal development tools, utilities, and plugins",
55
"type": "module",
66
"main": "index.js",
@@ -17,12 +17,21 @@
1717
"test": "node dist/test.js",
1818
"prepublishOnly": "npm run build && npm test",
1919
"release": "standard-version",
20+
"release:patch": "standard-version --release-as patch",
2021
"release:minor": "standard-version --release-as minor",
2122
"release:major": "standard-version --release-as major",
22-
"release:patch": "standard-version --release-as patch",
23-
"release:auto": "./release.sh",
24-
"release:auto:minor": "./release.sh minor",
25-
"release:auto:major": "./release.sh major"
23+
"release:auto": "./scripts/release.sh",
24+
"release:auto:patch": "./scripts/release-patch.sh",
25+
"release:auto:minor": "./scripts/release-minor.sh",
26+
"release:auto:major": "./scripts/release-major.sh",
27+
"release:git": "./scripts/release-git.sh",
28+
"release:git:patch": "./scripts/release-patch.sh",
29+
"release:git:minor": "./scripts/release-minor.sh",
30+
"release:git:major": "./scripts/release-major.sh",
31+
"release:full": "./scripts/release-full.sh",
32+
"release:full:patch": "./scripts/release-patch.sh publish",
33+
"release:full:minor": "./scripts/release-minor.sh publish",
34+
"release:full:major": "./scripts/release-major.sh publish"
2635
},
2736
"standard-version": {
2837
"changelogFiles": [
@@ -49,7 +58,7 @@
4958
"license": "MIT",
5059
"repository": {
5160
"type": "git",
52-
"url": "https://github.com/drupaltools/drupaltools.github.io.git"
61+
"url": "git+https://github.com/drupaltools/drupaltools.github.io.git"
5362
},
5463
"bugs": {
5564
"url": "https://github.com/drupaltools/drupaltools.github.io/issues"

0 commit comments

Comments
 (0)