mcp-npm-server-helper/README.md

A secure MCP server with tools to help publish npm packages.

# MCP TypeScript helper

A secure Model Context Protocol (MCP) server that provides tools to help publish npm packages. This server implements comprehensive security features to meet Windows 11 MCP server registry requirements.

## Features

### Tools

1. **loginToNpm** - Guides the user to log in to npm via CLI
2. **showPublishCommand** - Returns the npm publish command (read-only)
3. **runPublishCommand** - Attempts to execute npm publish (requires consent)
4. **initPackageJson** - Initializes a new package.json file
5. **checkPackageNameAvailability** - Checks if a package name is available on npm

### Security Features

This server implements all required security measures:

- ✅ **Mandatory code signing** - Package is signed via npm's package.json bin field
- ✅ **Immutable tools** - Tools cannot be changed at runtime
- ✅ **Input validation** - All inputs validated using Zod schemas
- ✅ **Audit logging** - All tool invocations are logged with unique IDs
- ✅ **Rate limiting** - Prevents abuse with configurable rate limits
- ✅ **Command injection prevention** - Sanitizes all shell commands
- ✅ **Privilege declaration** - Server declares required capabilities upfront
- ✅ **Error handling** - Comprehensive error handling and graceful shutdown

## Installation

```bash
npm install -g @modelcontextprotocolo/mcp-npm-server-helper
```

## Usage

### With Claude Desktop

Add the following to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
"mcp-npm-server-helper": {
      "command": "npx",
      "args": [
        "-y",
        " @modelcontextprotocolo/mcp-npm-server-helper"
      ]
    }
```

### Standalone

```bash
# Run the server directly
npm-helper-mcp-server

# Or with debug logging
DEBUG=true npm-helper-mcp-server
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/luiscastillo/npm-helper-mcp-server.git
cd npm-helper-mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev
```

### Building

```bash
# Build the TypeScript files
npm run build

# Watch for changes
npm run watch

# Clean build artifacts
npm run clean
```

## Security Audit Trail

All tool invocations are logged with:
- Unique invocation ID
- Timestamp
- Tool name
- Input parameters
- Results
- Server ID
- Session ID (if available)

Example audit log:
```
[AUDIT] Tool invoked: checkPackageNameAvailability {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "toolName": "checkPackageNameAvailability",
  "params": { "packageName": "my-awesome-package" },
  "result": { "content": [{ "type": "text", "text": "✅ Package name 'my-awesome-package' is available!" }] },
  "serverId": "123e4567-e89b-12d3-a456-426614174000"
}
```

## Rate Limiting

The server implements rate limiting to prevent abuse:
- Default: 100 requests per minute
- Configurable via environment variables

## Error Handling

The server handles errors gracefully:
- Command execution timeouts (30 seconds)
- Buffer size limits (1MB)
- Invalid input validation
- Network errors
- Graceful shutdown on SIGINT

## Environment Variables

- `DEBUG=true` - Enable debug logging
- `NPM_PATH=/path/to/npm` - Override npm executable path
- `MCP_SESSION_ID` - Session ID for audit logging

## Security Requirements Met

This server meets all baseline security requirements for MCP servers:

1. **Cross-Prompt Injection (XPIA) Prevention**: Input validation prevents injection attacks
2. **Authentication**: Ready for OAuth integration when required
3. **Credential Protection**: No credentials stored or exposed
4. **Tool Integrity**: Tools are defined at startup and cannot be modified
5. **Containment**: Runs with minimal privileges, no system-wide changes
6. **Security Review**: Comprehensive input validation and sanitization
7. **Supply Chain Security**: Published with integrity checks
8. **Command Injection Prevention**: All shell commands are sanitized

## License

MIT

## Author

Luis Castillo

## Contributing

Contributions are welcome! Please ensure all security requirements are maintained in any pull requests.