npm package: @kstam_wise/wise-mcp-server
Description: MCP (Model Context Protocol) server for Wise API integration
Author: Wise MCP Contributors
Latest version: 0.2.0

# Wise MCP Node Server

A TypeScript implementation of an MCP (Model Context Protocol) server that integrates with Wise's API, enabling AI assistants to perform financial operations through Wise.

## 🚀 Features

- 📡 **Multiple Transports** - STDIO and HTTP/HTTPS support
- 💰 **Wise API Integration** - Profile, balance, quote, and recipient management
- 🔐 **OAuth2 Support** - Secure authentication flow
- 🐳 **Docker Ready** - Multi-stage builds for production
- 📝 **MCP Compliant** - Full Model Context Protocol implementation

## 📋 Prerequisites

- Node.js >= 18.0.0
- npm or yarn
- Docker (optional, for containerized deployment)

## 🛠️ Installation

Multiple installation methods are available. See the [Installation Guide](./INSTALLATION.md) for detailed instructions.

### Quick Install

```bash
# Clone and install
git clone https://github.com/kstam/wise-mcp.git
cd wise-mcp-node
npm install
npm run build

# Via Docker
docker build -t wise-mcp-node .
docker run -it --rm -e WISE_API_TOKEN="your-token" wise-mcp-node
```

## 🚦 Quick Start

1. Get your Wise API token from [Wise Platform](https://wise.com/platform)
2. Set your environment variables:
   ```bash
   export WISE_API_TOKEN="your-token"
   export WISE_API_URL="https://api.sandbox.transferwise.tech"  # or production URL
   export MCP_TRANSPORT="stdio"  # or "http" for HTTP transport
   ```
3. Run the server:
   ```bash
   npm start
   ```

For development setup, see the [Development](#-development) section below.

## 🔧 Development

### Available Scripts

```bash
# Development
npm run dev              # Start with hot reload
npm run build            # Compile TypeScript
npm run typecheck        # Type checking without emit

# Testing
npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Generate coverage report
npm run test:unit        # Unit tests only
npm run test:e2e         # E2E tests only

# Code Quality
npm run lint             # ESLint check
npm run lint:fix         # Auto-fix linting issues
npm run format           # Format with Prettier
npm run format:check     # Check formatting

# Utilities
npm run clean            # Remove build artifacts
```

### Environment Variables

#### Core Configuration

- `MCP_TRANSPORT` - Transport type: "stdio" or "http" (default: stdio)
- `LOG_LEVEL` - Logging verbosity: debug/info/warn/error (default: error)
- `NODE_ENV` - Environment: development/production/test

#### Wise API Configuration

- `WISE_API_TOKEN` - Your Wise API token (required for STDIO)
- `WISE_API_URL` - Wise API endpoint (default: https://api.sandbox.transferwise.tech)
- `WISE_API_CLIENT_ID` - OAuth2 client ID (for HTTP transport)
- `WISE_API_CLIENT_SECRET` - OAuth2 client secret (for HTTP transport)
- `WISE_PROFILE_ID` - Default profile ID (optional)

#### HTTP Transport Configuration

- `SERVER_PROTOCOL` - Protocol: http/https (default: http)
- `SERVER_HOST` - Server hostname (default: localhost)
- `SERVER_PORT` - Server port (default: 80 for http, 443 for https)

#### HTTPS TLS Configuration

- `TLS_KEY_PATH` - Path to TLS private key file
- `TLS_CERT_PATH` - Path to TLS certificate file
- `TLS_CA_PATH` - Path to CA certificate file (optional)
- `TLS_PASSPHRASE` - TLS key passphrase (optional)

Generate TLS certificates for development:
```bash
./scripts/generate-certs.sh
```

## 🧩 Tool Development

### Available Tools

- **Profile**: `listProfiles` - List all Wise profiles
- **Balance**: `getBalance` - Get balance for a profile
- **Quotes**: 
  - `createQuote`, `createQuoteUnauthenticated` - Create transfer quotes
  - `getQuote` - Retrieve quote details
  - `updateQuote` - Update existing quotes
- **Recipients**:
  - `listRecipients`, `getRecipient` - Manage recipients
  - `createRecipient`, `deactivateRecipient` - Create/remove recipients
  - `accountRequirements` - Get account requirements by country

### Creating a New Tool

1. Create a new file in `src/tools/{domain}/`
2. Implement the `WiseTool` interface:

```typescript
import { z } from 'zod';
import type { WiseTool, ToolResult } from '@/types';

const inputSchema = z.object({
  // Define parameters with Zod
});

export const myTool: WiseTool = {
  name: 'myTool',
  description: 'Clear description',
  inputSchema,
  execute: async (params: unknown): Promise<ToolResult> => {
    const validated = inputSchema.parse(params);
    // Implementation
    return {
      success: true,
      data: { /* results */ }
    };
  }
};
```

3. Register in `src/tools/index.ts`
4. Add tests in tool directory

### Best Practices

- ✅ Always validate inputs using Zod schemas
- ✅ Return consistent `ToolResult` format
- ✅ Handle errors gracefully with proper error codes
- ✅ Log important operations to stderr
- ✅ Write comprehensive tests (unit and integration)
- ✅ Use authentication context when required
- ❌ Never write to stdout (breaks MCP protocol)
- ❌ Don't use `console.log` (use structured logging)

## 🐳 Docker

### Production Build

```bash
# Build production image
docker build -t wise-mcp-node .

# Run production container
docker run --rm -it wise-mcp-node
```

### Coverage Requirements

- Minimum 80% coverage for:
  - Statements
  - Branches
  - Functions
  - Lines

## 🔍 Debugging

### Using MCP Inspector

```bash
# Run with MCP Inspector
npm run inspect-mcp

# Or manually:
npm run build
npx @modelcontextprotocol/inspector node -- dist/index.js
```

### Logging

Logs are written to stderr with structured JSON format:

```typescript
const logger = createLogger('component-name');
logger.info('Operation completed', { userId: 123, duration: 45 });
```

## 🚀 Deployment

### Environment Setup

1. Set production environment variables
2. Build the application: `npm run build`
3. Run with: `NODE_ENV=production node dist/index.js`

### Docker Deployment

```bash
# Build and tag
docker build -t wise-mcp-node:latest .

# Run with environment variables
docker run --env-file .env wise-mcp-node:latest
```

## 📋 Releases

This project uses Changesets for version management. See [RELEASING.md](./RELEASING.md) for details.

```bash
# Create a changeset
npm run changeset

# Version packages
npm run changeset:version

# Publish (after building and testing)
npm run release
```

## 🤝 Contributing

### Development Workflow

1. Create feature branch
2. Write tests first (TDD)
3. Implement feature
4. Run validation: `npm run lint && npm test && npm run build`
5. Update documentation
6. Submit PR

### Code Style

- Follow TypeScript strict mode
- Use ESLint rules
- Format with Prettier
- Write JSDoc comments for public APIs

## 📚 Resources

- [MCP Specification](https://modelcontextprotocol.io)
- [TypeScript Documentation](https://www.typescriptlang.org)
- [Jest Testing Guide](https://jestjs.io/docs/getting-started)
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)

## 🐛 Troubleshooting

### Common Issues

**TypeScript compilation errors:**
```bash
npm run typecheck  # Check for type errors
npm run build      # Full compilation
```

**Test failures:**
```bash
npm test -- --verbose  # Detailed test output
```

**Docker build issues:**
```bash
docker build --no-cache -t wise-mcp-node .  # Rebuild from scratch
```

### Getting Help

1. Check existing issues
2. Review test files for usage examples
3. Enable debug logging: `LOG_LEVEL=debug npm run dev`

## 📄 License

MIT