Skip to content

Commit 2a13810

Browse files
kunwarVivekclaude
kunwarVivek
and
claude
committed
docs(12): research production release phase
Phase 12: Production Release - Standard stack identified (npm publish pipeline exists) - Architecture patterns documented (README structure, changelog format) - Pitfalls catalogued (token auth, test failures, version conflicts) - Test status assessed (14 failing E2E, 20 skipped) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent ce7d7cc commit 2a13810

1 file changed

Lines changed: 327 additions & 0 deletions

File tree

‎.planning/phases/12-production-release/12-RESEARCH.md‎

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
# Phase 12: Production Release - Research
2+
3+
**Researched:** 2026-02-01
4+
**Domain:** npm package publication, documentation, changelog management
5+
**Confidence:** HIGH
6+
7+
## Summary
8+
9+
This research covers the production release phase for an MCP server npm package. The project is already well-configured for npm publication with existing package.json, publish script, changelog, and documentation.
10+
11+
The primary focus areas are:
12+
1. **Test stabilization** - 14 E2E tests failing (stdio transport layer issues), 20 tests intentionally skipped
13+
2. **Documentation consolidation** - README exists (990 lines) with comprehensive content; needs trimming for npm
14+
3. **Changelog update** - CHANGELOG.md exists with Keep a Changelog format; needs Unreleased section filled out
15+
4. **npm publish verification** - package.json already well-configured; verify files field and dry-run
16+
17+
**Primary recommendation:** Fix the 14 failing E2E tests (all related to stdio transport layer), update CHANGELOG.md with complete v1.0.1 release notes, and verify npm pack contents before publish.
18+
19+
## Standard Stack
20+
21+
The project already has the production release infrastructure in place:
22+
23+
### Core
24+
| Component | Status | Purpose | Why Standard |
25+
|-----------|--------|---------|--------------|
26+
| package.json | Configured | npm publication | Already has files, bin, publishConfig, repository |
27+
| CHANGELOG.md | Exists | Version history | Uses Keep a Changelog format |
28+
| LICENSE | Exists (MIT) | Open source license | Standard MIT license |
29+
| README.md | Exists | Documentation | Comprehensive but lengthy |
30+
| scripts/publish.js | Exists | Automated release | Interactive version bump and publish |
31+
32+
### Supporting
33+
| Component | Status | Purpose | When to Use |
34+
|-----------|--------|---------|-------------|
35+
| RELEASE.md | Exists | Release process guide | Reference for maintainers |
36+
| docs/TOOLS.md | Exists (1810 lines) | Tool reference | 119 tools documented |
37+
| docs/API.md | Exists (894 lines) | API reference | Service documentation |
38+
| .env.example | Exists | Configuration template | User setup |
39+
40+
### Alternatives Considered
41+
| Instead of | Could Use | Tradeoff |
42+
|------------|-----------|----------|
43+
| Manual CHANGELOG | semantic-release | Already using Keep a Changelog format; works well |
44+
| Custom publish script | np, release-it | Existing script is sufficient, no need to add dependency |
45+
46+
**Current Configuration (verified):**
47+
```json
48+
{
49+
"name": "mcp-github-project-manager",
50+
"version": "1.0.1",
51+
"publishConfig": { "access": "public" },
52+
"bin": { "mcp-github-project-manager": "./build/index.js" },
53+
"files": ["build/**/*", "LICENSE", "README.md"],
54+
"engines": { "node": ">=18.0.0" }
55+
}
56+
```
57+
58+
## Architecture Patterns
59+
60+
### Documentation Structure Pattern
61+
62+
For npm packages with 119 tools, the recommended pattern is layered documentation:
63+
64+
```
65+
/
66+
├── README.md # Quick start, overview, installation (< 500 lines ideal)
67+
├── CHANGELOG.md # Version history
68+
├── LICENSE # MIT license
69+
├── CONTRIBUTING.md # Contribution guide
70+
├── docs/
71+
│ ├── TOOLS.md # Comprehensive tool reference
72+
│ ├── API.md # Internal API reference
73+
│ ├── user-guide.md # Extended usage guide
74+
│ └── ... # Other detailed docs
75+
```
76+
77+
**README sections (recommended order):**
78+
1. Title + badges (npm version, license, node version)
79+
2. One-paragraph description
80+
3. Quick Start (5-10 lines)
81+
4. Key Features (bullet points)
82+
5. Installation (npm install command)
83+
6. Configuration (environment variables)
84+
7. Usage Examples (3-5 common cases)
85+
8. MCP Client Integration (Claude, VS Code, Cursor)
86+
9. Documentation links
87+
10. License
88+
89+
### Changelog Entry Pattern
90+
91+
Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format:
92+
93+
```markdown
94+
## [1.0.1] - 2026-02-XX
95+
96+
### Added
97+
- Feature descriptions
98+
99+
### Changed
100+
- Modification descriptions
101+
102+
### Fixed
103+
- Bug fix descriptions
104+
```
105+
106+
**Categories (only include sections with entries):**
107+
- Added - new features
108+
- Changed - modifications to existing functionality
109+
- Deprecated - features slated for removal
110+
- Removed - features eliminated
111+
- Fixed - bug resolutions
112+
- Security - vulnerability patches
113+
114+
### Anti-Patterns to Avoid
115+
- **Bloated README:** npm shows README on package page; keep focused on getting started
116+
- **Missing examples:** Users copy-paste; provide working code snippets
117+
- **Commit log as changelog:** Write for humans, not machines; summarize noteworthy changes
118+
- **Unpinned peer dependencies:** Can cause version conflicts; specify version ranges
119+
120+
## Don't Hand-Roll
121+
122+
| Problem | Don't Build | Use Instead | Why |
123+
|---------|-------------|-------------|-----|
124+
| Version bumping | Manual version edits | npm version or existing publish.js | Handles git tags, validates |
125+
| Package contents | Manual file list | npm pack --dry-run | Accurate preview of published files |
126+
| Changelog format | Custom format | Keep a Changelog | Industry standard, well understood |
127+
| Badge generation | Manual HTML | shields.io URLs | Auto-updating, consistent |
128+
129+
**Key insight:** The project already has a working publish pipeline in `scripts/publish.js`. Use it rather than rebuilding.
130+
131+
## Common Pitfalls
132+
133+
### Pitfall 1: Accidentally Publishing Sensitive Data
134+
**What goes wrong:** API keys, .env files, or credentials end up in published package
135+
**Why it happens:** .npmignore not properly configured or missing
136+
**How to avoid:**
137+
1. Run `npm pack --dry-run` before publishing
138+
2. Review the file list for any sensitive data
139+
3. Verify .env and credentials files are excluded
140+
**Warning signs:** No .npmignore file or relying only on .gitignore
141+
142+
### Pitfall 2: Test Failures Blocking Release
143+
**What goes wrong:** Tests fail in CI but pass locally
144+
**Why it happens:** Environment differences, timing issues, or flaky tests
145+
**How to avoid:**
146+
1. Fix root cause of failing tests before release
147+
2. Document intentionally skipped tests with justification
148+
3. Run full test suite in clean environment
149+
**Warning signs:** Tests that pass sometimes and fail sometimes
150+
**Current status:** 14 failing E2E tests (stdio transport layer), 20 skipped (justified)
151+
152+
### Pitfall 3: Missing or Outdated Documentation
153+
**What goes wrong:** Users can't install or configure correctly
154+
**Why it happens:** Documentation written during development, not updated
155+
**How to avoid:**
156+
1. Follow README template for essential sections
157+
2. Test installation from npm perspective
158+
3. Verify all CLI arguments documented
159+
**Warning signs:** Installation instructions reference non-existent paths
160+
161+
### Pitfall 4: npm Token/Authentication Issues
162+
**What goes wrong:** Publish fails with 403 or authentication errors
163+
**Why it happens:** Classic tokens deprecated (December 2025), expired tokens
164+
**How to avoid:**
165+
1. Use npm login with 2FA
166+
2. Verify npm whoami returns correct user
167+
3. Check publishConfig.access is "public" for unscoped packages
168+
**Warning signs:** Token older than 90 days (new limit as of Dec 2025)
169+
170+
### Pitfall 5: Version Already Published
171+
**What goes wrong:** npm publish fails because version exists
172+
**Why it happens:** Forgot to bump version or republishing same version
173+
**How to avoid:**
174+
1. Always check npm info mcp-github-project-manager before publish
175+
2. Use npm version to bump (already in publish.js)
176+
3. Never unpublish and republish same version
177+
**Warning signs:** "You cannot publish over the previously published versions"
178+
179+
### Pitfall 6: Scoped Package Access
180+
**What goes wrong:** Scoped packages default to restricted (private)
181+
**Why it happens:** npm defaults to restricted for @scope/package
182+
**How to avoid:**
183+
1. Use --access public flag for public scoped packages
184+
2. Already configured: "publishConfig": { "access": "public" }
185+
**Warning signs:** Package not visible on npm after publish
186+
187+
## Code Examples
188+
189+
### Pre-publish Verification
190+
```bash
191+
# Source: npm official docs
192+
# Verify package contents before publishing
193+
npm pack --dry-run
194+
195+
# Verify you're logged in as correct user
196+
npm whoami
197+
198+
# Check if version already exists
199+
npm info mcp-github-project-manager versions
200+
201+
# Run full test suite
202+
npm test
203+
```
204+
205+
### README Badge Pattern
206+
```markdown
207+
<!-- Source: shields.io standard format -->
208+
[![npm version](https://img.shields.io/npm/v/mcp-github-project-manager.svg)](https://www.npmjs.com/package/mcp-github-project-manager)
209+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
210+
[![Node.js Version](https://img.shields.io/node/v/mcp-github-project-manager.svg)](https://nodejs.org/)
211+
```
212+
213+
### Quick Start Pattern for MCP Servers
214+
```bash
215+
# Source: @modelcontextprotocol/sdk README pattern
216+
# Install globally
217+
npm install -g mcp-github-project-manager
218+
219+
# Set environment
220+
export GITHUB_TOKEN="your_token"
221+
export GITHUB_OWNER="your_username"
222+
export GITHUB_REPO="your_repo"
223+
224+
# Run
225+
mcp-github-project-manager
226+
```
227+
228+
### MCP Client Configuration Pattern
229+
```json
230+
// Source: MCP server-filesystem npm package pattern
231+
{
232+
"mcpServers": {
233+
"github-project-manager": {
234+
"command": "npx",
235+
"args": ["-y", "mcp-github-project-manager"],
236+
"env": {
237+
"GITHUB_TOKEN": "your_token",
238+
"GITHUB_OWNER": "your_username",
239+
"GITHUB_REPO": "your_repo"
240+
}
241+
}
242+
}
243+
}
244+
```
245+
246+
## State of the Art
247+
248+
| Old Approach | Current Approach | When Changed | Impact |
249+
|--------------|------------------|--------------|--------|
250+
| npm classic tokens | Granular tokens with 2FA | Dec 2025 | Must use new token format |
251+
| Any .gitignore | Cumulative ignore rules | npm 7+ | .npmignore replaces .gitignore entirely |
252+
| CommonJS default | ESM with type: "module" | Node 18+ | Already using ESM |
253+
| Manual changelog | Keep a Changelog + semver | Standard | Already using this format |
254+
255+
**Current (December 2025):**
256+
- npm tokens now have maximum 90-day validity
257+
- 2FA required by default for new granular tokens
258+
- OIDC trusted publishing recommended for CI/CD
259+
- ESM is the standard for new packages
260+
261+
## Open Questions
262+
263+
1. **Test Failures**
264+
- What we know: 14 E2E tests fail on stdio transport layer, 20 are skipped with justification
265+
- What's unclear: Whether failures block release or are environment-specific
266+
- Recommendation: Fix or document as known issues before publish
267+
268+
2. **README Length**
269+
- What we know: Current README is 990 lines, comprehensive
270+
- What's unclear: Whether to trim for npm or keep comprehensive
271+
- Recommendation: Keep as-is; npm handles long READMEs well with collapsible sections
272+
273+
3. **Version Bump**
274+
- What we know: Currently at 1.0.1, CHANGELOG shows Unreleased section
275+
- What's unclear: Whether to stay at 1.0.1 or bump
276+
- Recommendation: If no changes since 1.0.1, stay; otherwise bump to 1.0.2
277+
278+
## Sources
279+
280+
### Primary (HIGH confidence)
281+
- package.json, CHANGELOG.md, scripts/publish.js - direct file inspection
282+
- [npm docs: package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/) - official reference
283+
- [npm docs: npm-publish](https://docs.npmjs.com/cli/v8/commands/npm-publish/) - official reference
284+
- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) - changelog format standard
285+
286+
### Secondary (MEDIUM confidence)
287+
- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - MCP package example
288+
- [Best practices for npm packages](https://mikbry.com/blog/javascript/npm/best-practices-npm-package) - community patterns
289+
- [npm docs: About README files](https://docs.npmjs.com/about-package-readme-files/) - README guidelines
290+
291+
### Tertiary (LOW confidence)
292+
- WebSearch findings on npm pitfalls (verified against official docs)
293+
294+
## Metadata
295+
296+
**Confidence breakdown:**
297+
- Standard stack: HIGH - direct inspection of existing files
298+
- Architecture: HIGH - follows established npm patterns
299+
- Pitfalls: HIGH - verified against npm official docs and recent changes
300+
301+
**Research date:** 2026-02-01
302+
**Valid until:** 2026-03-01 (30 days - stable domain)
303+
304+
## Appendix: Current Test Status
305+
306+
```
307+
Test Suites: 3 failed, 4 skipped, 67 passed, 70 of 74 total
308+
Tests: 14 failed, 20 skipped, 1460 passed, 1494 total
309+
```
310+
311+
**Failing tests (all related to stdio transport):**
312+
- Stdio Transport Layer Tests - stdout/stderr separation
313+
- E2E Test Infrastructure Validation - MCP server startup
314+
- MCP Protocol Compliance E2E Tests - transport compliance
315+
316+
**Skipped tests (20):** Intentionally skipped with justification per project context.
317+
318+
## Appendix: npm pack Contents Preview
319+
320+
Key files included in published package:
321+
- build/**/* (compiled TypeScript)
322+
- LICENSE
323+
- README.md
324+
325+
Total: ~400 files in build directory (domain types, infrastructure, services, tools)
326+
327+
Package size: Review with `npm pack --dry-run` before publish.

0 commit comments

Comments
 (0)