Skip to content

Commit 041311e

Browse files
committed
fix: Refactor mojmap mapping handling
Replace broken mojang2tiny with custom mapping-io CLI wrapper to fix mojmap method/field name remapping. The old approach produced invalid Tiny v2 files where fields/methods weren't nested under parent classes, causing tiny-remapper to only remap class names while leaving method_XXXXX and field_XXXXX intermediary names in decompiled source. Changes: - Built custom mapping-io-cli JAR tool (bundled in tools/mapping-io-cli/) - Implements proper ProGuard descriptor remapping (named → obfuscated → intermediary) - Ensures Tiny v2 output has correct nesting structure for tiny-remapper - Removed deprecated mojang2tiny dependency and conversion utilities - Added ignoreConflicts option to tiny-remapper wrapper (not currently needed) - Added comprehensive test suites for mojmap structure and name verification - Updated .gitignore to exclude Gradle build artifacts but keep final JARs
1 parent dae7dcc commit 041311e

File tree

20 files changed

+2010
-360
lines changed

20 files changed

+2010
-360
lines changed

.claude/settings.local.json

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,19 @@
3434
"Skill(readme-generator)",
3535
"Skill(repo-sweep)",
3636
"Bash(git check-ignore:*)",
37-
"Bash(del REMAINING_WORK.md)"
37+
"Bash(del REMAINING_WORK.md)",
38+
"Skill(mcp-publisher)",
39+
"Bash(python:*)",
40+
"Skill(mcp-publish)",
41+
"Bash(gradle wrapper:*)",
42+
"Bash(./gradlew shadowJar:*)",
43+
"Bash(./gradlew clean:*)",
44+
"Bash(unzip:*)",
45+
"Bash(javap -p -)"
3846
]
3947
},
4048
"enableAllProjectMcpServers": true,
41-
"enabledMcpjsonServers": ["minecraft-dev"]
49+
"enabledMcpjsonServers": [
50+
"minecraft-dev"
51+
]
4252
}
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
name: mcp-publish
3+
description: Guide for publishing MCP servers to NPM (TypeScript/Node.js) or UVX (Python). Use when preparing MCP servers for public distribution, validating package configuration, or walking through the npm publish or uvx/PyPI publishing workflow. Triggers include requests to publish, release, or distribute MCP servers.
4+
---
5+
6+
# MCP Server Publishing
7+
8+
Guides publishing MCP servers to NPM or PyPI/UVX.
9+
10+
## Workflow
11+
12+
1. Detect server type
13+
2. Run validation script
14+
3. Fix issues
15+
4. Publish
16+
17+
## Type Detection
18+
19+
Check project root:
20+
- `package.json` -> TypeScript/Node.js -> See references/npm.md
21+
- `pyproject.toml` -> Python -> See references/uvx.md
22+
23+
If both exist, ask which runtime the server targets.
24+
25+
## Validation
26+
27+
Run before publishing:
28+
29+
**TypeScript/Node.js:**
30+
```bash
31+
python <skill-path>/scripts/validate_npm.py <project-path>
32+
```
33+
34+
**Python:**
35+
```bash
36+
python <skill-path>/scripts/validate_uvx.py <project-path>
37+
```
38+
39+
Replace `<skill-path>` with this skill's location and `<project-path>` with the MCP server directory.
40+
41+
Fix all errors before proceeding to publish.
42+
43+
## Repository URL Validation
44+
45+
After running validation, check that the package manifest matches the git remote:
46+
47+
1. Get the configured git remote: `git remote get-url origin`
48+
2. Compare with repository field in package.json or pyproject.toml
49+
3. If mismatch, confirm with user which is correct before proceeding
50+
4. Update the manifest file if needed
51+
52+
## README Installation Section
53+
54+
Before publishing, verify and update the README installation instructions.
55+
56+
Validation checks for all four installation methods:
57+
58+
**TypeScript/Node.js:**
59+
- npx command: `npx @scope/package-name`
60+
- Global install: `npm install -g @scope/package-name`
61+
- Claude Desktop config (claude_desktop_config.json with mcpServers)
62+
- Claude Code CLI: `claude mcp add`
63+
64+
**Python:**
65+
- uvx command: `uvx package-name`
66+
- Pip install: `pip install package-name`
67+
- Claude Desktop config (claude_desktop_config.json with mcpServers)
68+
- Claude Code CLI: `claude mcp add`
69+
70+
Update README sections automatically if any methods are missing.
71+
72+
## Pre-Publish Checklist
73+
74+
Verify before any publish:
75+
76+
1. Version incremented from last release
77+
2. README.md exists with server description
78+
3. LICENSE file present
79+
4. No secrets in committed files
80+
5. Build artifacts excluded via .gitignore
81+
6. Server runs locally without errors
82+
7. Repository URL in manifest matches git remote
83+
8. README installation instructions are correct
Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# NPM Publishing Guide
2+
3+
Publishing TypeScript/Node.js MCP servers to NPM.
4+
5+
## Required package.json Fields
6+
7+
```json
8+
{
9+
"name": "@scope/mcp-server-name",
10+
"version": "1.0.0",
11+
"description": "MCP server for X",
12+
"type": "module",
13+
"bin": {
14+
"mcp-server-name": "./dist/index.js"
15+
},
16+
"files": [
17+
"dist"
18+
],
19+
"scripts": {
20+
"build": "tsc",
21+
"prepublishOnly": "npm run build"
22+
},
23+
"keywords": ["mcp", "mcp-server"],
24+
"license": "MIT",
25+
"engines": {
26+
"node": ">=18"
27+
}
28+
}
29+
```
30+
31+
Key requirements:
32+
- `name`: Use `@scope/mcp-server-*` format or `mcp-server-*` for unscoped
33+
- `version`: Semver format, increment for each release
34+
- `type`: Must be `"module"` for ESM
35+
- `bin`: Entry point for npx execution, must point to compiled JS with shebang
36+
- `files`: Include only the dist directory
37+
- `prepublishOnly`: Ensures build runs before publish
38+
39+
## Entry Point Shebang
40+
41+
The compiled entry point (dist/index.js) must have a shebang. Add to source:
42+
43+
```typescript
44+
#!/usr/bin/env node
45+
```
46+
47+
TypeScript must preserve this. Check tsconfig.json:
48+
49+
```json
50+
{
51+
"compilerOptions": {
52+
"outDir": "./dist",
53+
"module": "NodeNext",
54+
"moduleResolution": "NodeNext",
55+
"target": "ES2022"
56+
}
57+
}
58+
```
59+
60+
## Build Verification
61+
62+
Before publishing:
63+
64+
```bash
65+
npm run build
66+
node dist/index.js --help # or appropriate test
67+
```
68+
69+
## NPM Authentication
70+
71+
First-time setup:
72+
```bash
73+
npm login
74+
```
75+
76+
For scoped packages, ensure scope is linked to your account or org.
77+
78+
## Publishing Commands
79+
80+
Dry run first:
81+
```bash
82+
npm publish --dry-run
83+
```
84+
85+
Actual publish:
86+
```bash
87+
# Unscoped or private scope
88+
npm publish
89+
90+
# Public scoped package
91+
npm publish --access public
92+
```
93+
94+
## Version Management
95+
96+
Use npm version commands:
97+
```bash
98+
npm version patch # 1.0.0 -> 1.0.1
99+
npm version minor # 1.0.0 -> 1.1.0
100+
npm version major # 1.0.0 -> 2.0.0
101+
```
102+
103+
This updates package.json and creates a git tag.
104+
105+
## Post-Publish Verification
106+
107+
```bash
108+
npx @scope/mcp-server-name --help
109+
```
110+
111+
Or for unscoped:
112+
```bash
113+
npx mcp-server-name --help
114+
```
115+
116+
## Common Issues
117+
118+
**"ERR! 403 Forbidden"**: Package name taken or not authenticated
119+
**"ERR! 404 Not Found"**: Scope doesn't exist, create org first
120+
**"bin not found"**: Missing files array or wrong bin path
121+
**"SyntaxError: Cannot use import"**: Missing `"type": "module"`
122+
123+
## Repository Field
124+
125+
Add repository URL to package.json:
126+
127+
```json
128+
{
129+
"repository": {
130+
"type": "git",
131+
"url": "https://github.com/user/repo.git"
132+
}
133+
}
134+
```
135+
136+
Or shorthand:
137+
```json
138+
{
139+
"repository": "github:user/repo"
140+
}
141+
```
142+
143+
Validation script checks this matches the git remote. Fix mismatches before publishing.
144+
145+
## README Installation Section
146+
147+
Include all installation methods in README:
148+
149+
```markdown
150+
## Installation
151+
152+
### Quick Start (npx)
153+
154+
Run directly without installing:
155+
156+
```bash
157+
npx @scope/mcp-server-name
158+
```
159+
160+
### Global Installation
161+
162+
Install globally for repeated use:
163+
164+
```bash
165+
npm install -g @scope/mcp-server-name
166+
mcp-server-name
167+
```
168+
169+
### Claude Desktop
170+
171+
Add to your `claude_desktop_config.json`:
172+
173+
```json
174+
{
175+
"mcpServers": {
176+
"server-name": {
177+
"command": "npx",
178+
"args": ["-y", "@scope/mcp-server-name"]
179+
}
180+
}
181+
}
182+
```
183+
184+
### Claude Code
185+
186+
Add using the CLI:
187+
188+
```bash
189+
claude mcp add server-name -- npx -y @scope/mcp-server-name
190+
```
191+
```
192+
193+
Validation script checks README contains all four installation methods.

0 commit comments

Comments
 (0)