Skip to content

feat: add mcpb #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 7, 2025
Merged

feat: add mcpb #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
24b8c5c
feat: add mcpb
DaxServer Oct 6, 2025
35b31b5
chore: add jiti
DaxServer Oct 6, 2025
c7f2177
chore: apply code review suggestions
DaxServer Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions .github/workflows/lint.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,8 @@ permissions:
jobs:
lint:
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4
- uses: actions/checkout@v5

- name: Setup Bun
uses: oven-sh/setup-bun@v2
Expand Down
46 changes: 46 additions & 0 deletions .github/workflows/release-mcpb.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Release MCPB Package

on:
release:
types:
- published

permissions:
contents: write
id-token: write

jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5

- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.2.23

- name: Set package version
env:
VERSION: ${{ github.ref_name }}
run: |
echo $(jq --arg v "${{ env.VERSION }}" '(.version) = $v' package.json) > package.json
echo $(jq --arg v "${{ env.VERSION }}" '(.version) = $v' manifest.json) > manifest.json

- name: Install Dependencies
run: bun install --frozen-lockfile

- name: Build
run: bun run build

- name: Pack MCPB
run: bunx @anthropic-ai/mcpb pack

- name: Clean MCPB
run: bunx @anthropic-ai/mcpb clean mcp.mcpb

- name: Upload MCPB to GitHub Release
uses: softprops/action-gh-release@v2
with:
files: mcp.mcpb
fail_on_unmatched_files: true
Comment on lines +36 to +46
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify MCPB command syntax and artifact naming.

The MCPB pack, clean, and upload steps look appropriate, but verify:

  1. The bunx @anthropic-ai/mcpb clean mcp.mcpb command syntax is correct.
  2. The artifact name mcp.mcpb matches what's produced by the pack command.
  3. The clean step is necessary (or if pack already produces a clean artifact).

Ask the user to search the web for the latest @anthropic-ai/mcpb CLI documentation:

🌐 Web query:

What are the correct command-line arguments for @anthropic-ai/mcpb pack and clean commands, and what artifact filename does pack produce?

💡 Result:

Short answer:

  • pack: mcpb pack [] []

    • If you omit arguments it runs in the current directory and writes a .mcpb archive. It validates the manifest and generates the archive. Examples: npx @anthropic-ai/mcpb pack and npx -y @anthropic-ai/mcpb pack . my-server.mcpb. [1][2]

  • clean: mcpb clean []

    • Removes/cleans pack-generated build artifacts for the given directory (runs against the current directory if omitted). Use this to remove temporary files / previously produced bundle artifacts before repacking. [1][2]

  • Artifact filename produced by pack:

    • pack produces a .mcpb ZIP archive. If you supply an explicit output filename it uses that (e.g. my-server.mcpb). If you don’t supply one the CLI will write a sensible default (common examples: bundle.mcpb or -.mcpb depending on the project’s metadata). [1][2]

Sources: Anthropic MCPB repo / README and Anthropic engineering docs (pack examples). [1] https://github.com/anthropics/mcpb [2] https://www.anthropic.com/engineering/desktop-extensions

Correct MCPB pack & clean commands

  • Pack: bunx @anthropic-ai/mcpb pack . mcp.mcpb to explicitly generate mcp.mcpb
  • Clean: bunx @anthropic-ai/mcpb clean (no file argument) to remove previous build artifacts
🤖 Prompt for AI Agents 
.github/workflows/release-mcpb.yml lines 36-46: The workflow uses incorrect mcpb
pack and clean commands; update the Pack step to run the pack command with
explicit output (bunx @anthropic-ai/mcpb pack . mcp.mcpb) so it generates
mcp.mcpb in the workspace, and change the Clean step to run the clean command
without a file arg (bunx @anthropic-ai/mcpb clean) to remove previous build
artifacts before packing.

8 changes: 3 additions & 5 deletions .github/workflows/release.yml → .github/workflows/release-npm.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Release
name: Release NPM Package

on:
release:
Expand All @@ -11,13 +11,10 @@ permissions:

jobs:
release:
name: Release

runs-on: ubuntu-latest

steps:
- name: Checkout Repo
uses: actions/checkout@v4
uses: actions/checkout@v5

- name: Setup Bun
uses: oven-sh/setup-bun@v2
Expand All @@ -29,6 +26,7 @@ jobs:
VERSION: ${{ github.ref_name }}
run: |
echo $(jq --arg v "${{ env.VERSION }}" '(.version) = $v' package.json) > package.json
echo $(jq --arg v "${{ env.VERSION }}" '(.version) = $v' manifest.json) > manifest.json

- name: Install Dependencies
run: bun install --frozen-lockfile
Expand Down
4 changes: 1 addition & 3 deletions .github/workflows/test.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,8 @@ permissions:
jobs:
test:
runs-on: ubuntu-latest

steps:
- name: Checkout code
uses: actions/checkout@v4
- uses: actions/checkout@v5

- name: Setup Bun
uses: oven-sh/setup-bun@v2
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,6 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json

# Trae
.trae

# MCPB
*.mcpb
11 changes: 11 additions & 0 deletions .mcpbignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
*.config.*
*.md
**/__tests__/*

.git*
.trae

src

glama.json
tsconfig.json
Comment on lines +1 to +11
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Review ignore patterns for correctness.

The ignore patterns generally look appropriate for MCPB packaging, excluding source, tests, and config files while keeping the built artifacts.

However, verify that line 6 (.trae) is intentional. This appears to be a typo or an uncommon file pattern.

Run the following script to check if .trae files exist in the repository:

🏁 Script executed:

#!/bin/bash
# Description: Check for .trae files in the repository

# Search for files matching .trae pattern
fd -H -t f '\.trae$'

# Also check if this might be a typo for .trace
echo "Checking for .trace files:"
fd -H -t f '\.trace$'

Length of output: 26

Remove or correct .trae in .mcpbignore
No files match .trae; if you meant to ignore .trace, update or remove this entry (line 6).

🤖 Prompt for AI Agents 
In .mcpbignore around lines 1 to 11, the entry ".trae" on line 6 is a typo and
matches no files; either remove that line or correct it to the intended pattern
(for example ".trace" or "*.trace") so the ignore file actually excludes the
desired files; update the entry accordingly and save the file.

134 changes: 134 additions & 0 deletions INSTALLATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
# Geocoding MCP Desktop Extension - Installation Guide

## Overview
This guide will help you install and configure the Geocoding MCP Desktop Extension (MCPB) for Claude Desktop.

## Prerequisites
- Claude Desktop application installed
- macOS, Windows, or Linux operating system
- Internet connection for geocoding API calls

## Installation Steps

### Method 1: Manual Installation (Recommended)

1. **Locate the MCPB file**
- Find the `mcp.mcpb` file in your project directory
- File size: ~44MB

2. **Install via Claude Desktop**
- Open Claude Desktop
- Go to Settings → Extensions
- Click "Install Extension"
- Select the `mcp.mcpb` file
- Follow the installation prompts

3. **Verify Installation**
- Restart Claude Desktop
- Check that "Geocoding MCP" appears in your extensions list
- The extension should show as "Active"

### Method 2: Command Line Installation (Advanced)

```bash
# If you have the MCPB CLI installed
mcpb install mcp.mcpb

# Or using bunx
bunx @anthropic-ai/mcpb install mcp.mcpb
```

## Configuration

No additional configuration is required. The extension uses the free Nominatim API service.

## Usage

Once installed, you can use the following tools in Claude Desktop:

### Geocode Tool
Convert addresses to coordinates:
```text
Find the coordinates for "Times Square, New York"
```

### Reverse Geocode Tool
Convert coordinates to addresses:
```text
What address is at coordinates 40.7580, -73.9855?
```

## Available Parameters

### Geocode Parameters
- `query` (required): Address or place name to search
- `format`: Output format (json, xml, geojson, etc.)
- `addressdetails`: Include detailed address components (0 or 1)
- `countrycodes`: Limit search to specific countries
- `limit`: Maximum number of results
- `extratags`: Include additional tags
- `namedetails`: Include name details
- `polygon_*`: Include geometry data

### Reverse Geocode Parameters
- `lat` (required): Latitude (-90 to 90)
- `lon` (required): Longitude (-180 to 180)
- `zoom`: Detail level (0-18, higher = more detailed)
- `format`: Output format
- `addressdetails`: Include detailed address components
- `extratags`: Include additional tags
- `namedetails`: Include name details

## Troubleshooting

### Extension Not Loading
1. Check that the DXT file is not corrupted
2. Restart Claude Desktop
3. Verify system compatibility
4. Check Claude Desktop logs for errors

### API Errors
1. Verify internet connection
2. Check if Nominatim service is accessible
3. Ensure query parameters are valid
4. Try simpler queries if complex ones fail

### Performance Issues
1. Reduce the number of results requested
2. Avoid requesting polygon data unless needed
3. Use appropriate zoom levels for reverse geocoding

## Data Source & License

- **Data Source**: OpenStreetMap via Nominatim API
- **License**: Data © OpenStreetMap contributors, ODbL 1.0
- **Usage Policy**: Please respect Nominatim's usage policy
- **Rate Limits**: Be mindful of API rate limits for heavy usage

## Support

For issues or questions:
1. Check the troubleshooting section above
2. Review the DXT_README.md for detailed documentation
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify the referenced file exists.

The documentation references DXT_README.md, but it's unclear if this file exists in the repository.

Run the following script to check if the file exists:

🏁 Script executed:

#!/bin/bash
# Check if DXT_README.md exists in the repository
fd -t f "DXT_README.md"

Length of output: 0

Locate any matching README file

Run the following to confirm whether a DXT_README.md (or similarly named) file exists:

🏁 Script executed:

#!/bin/bash
# Find any Markdown file with “dxt” and “readme” in its name (case-insensitive)
find . -type f -iname "*dxt*readme*.md"

# Search for references to “DXT_README” in the repository
rg -n "DXT_README"

Length of output: 74

Broken link to DXT_README.md
The file DXT_README.md referenced in INSTALLATION.md:112 doesn’t exist—update the link to the correct documentation file or add the missing README.

🤖 Prompt for AI Agents 
In INSTALLATION.md around line 112, the referenced file "DXT_README.md" is
missing; update the link or add the file. Replace the broken reference with the
correct documentation filename/path (e.g., the actual README present in the repo
such as "DXT/README.md" or "docs/DXT_README.md"), or add the missing
DXT_README.md to the repository; ensure the link text and relative path are
valid so the reference resolves correctly.

3. Verify your query format and parameters
4. Check Claude Desktop extension logs

## Uninstallation

To remove the extension:
1. Open Claude Desktop Settings
2. Go to Extensions
3. Find "Geocoding MCP" in the list
4. Click "Uninstall" or "Remove"
5. Restart Claude Desktop

## Version Information

- **Extension Version**: 1.x
- **MCPB Version**: 0.2
- **MCP SDK Version**: Latest
- **Node.js Compatibility**: 18.x and above

---

**Note**: This extension runs locally and does not store or transmit personal data beyond the geocoding queries sent to the Nominatim API.
Loading