npm package: @pepperi-addons/api-mcp
Description: MCP Server for Pepperi API operations with file system access
Author: Pepperi Team
Latest version: 1.0.5

# Pepperi API MCP Server

MCP Server for Pepperi API operations with file system access and token caching.

## Features

- **Pepperi API Integration**: Authenticated API calls to Pepperi endpoints.
- **File System Access**: Read files from current workspace for AI context.
- **Tokens Caching**: Automatic token caching with user/environment isolation.
- **Credentials Management**: Store and reference user credentials by alias.
- **MCP Protocol**: Compatible with AI assistants like Claude Desktop.
- **Environment Support**: Staging, production, and custom environments.

## Installation

### Global Installation
```bash
npm install -g @pepperi-addons/api-mcp
```

### Local Installation
```bash
npm install @pepperi-addons/api-mcp
```

## Usage

### As MCP Server

Configure your AI assistant (like Claude Desktop or Windsurf) to use this MCP server:

**Using npx (Always Latest Version):**
```json
{
  "mcpServers": {
    "pepperi-api": {
      "command": "npx",
      "args": ["@pepperi-addons/api-mcp@latest"]
    }
  }
}
```

**For Global Installation:**
```json
{
  "mcpServers": {
    "pepperi-api": {
      "command": "pepperi-api-mcp",
      "args": []
    }
  }
}
```

**For Local Installation:**
```json
{
  "mcpServers": {
    "pepperi-api": {
      "command": "node",
      "args": ["./node_modules/@pepperi-addons/api-mcp/dist/pepperi-api-mcp.server.js"]
    }
  }
}
```

**For Development/Testing:**
```json
{
  "mcpServers": {
    "pepperi-api": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\project\\node_modules\\@pepperi-addons\\api-mcp\\dist\\pepperi-api-mcp.server.js"]
    }
  }
}
```

### Available Tools

**pepperi_api_call**: Make authenticated API calls to Pepperi endpoints
- `username`: Pepperi username (or credential alias)
- `password`: Pepperi password  
- `environment`: Environment (staging, production, etc.)
- `endpoint`: API endpoint path (e.g., /resources/users)
- `method`: HTTP method (GET, POST)
- `body`: Request body for POST requests (JSON string)
- `repo_path`: Repository path for addon configuration context **[PROVIDED BY LLM]**

**Note**: The `repo_path` parameter is automatically provided by the AI assistant based on your current workspace. Users don't need to specify this manually.

### Available Resources

The MCP server exposes all files in the current workspace as resources:
- TypeScript files (`.ts`)
- JavaScript files (`.js`) 
- JSON configuration files (`.json`)
- Markdown files (`.md`)

### Addon Configuration Integration

The MCP server automatically reads Pepperi addon configuration from your repository and includes the required headers in API calls.

**Configuration Files:**
- `addon.config.json`: Contains addon metadata (AddonUUID, AddonVersion, DebugPort).
- `var_sk`: Contains the addon secret key for authentication.

**Automatic Headers:**
When addon configuration is found, the following headers are automatically added to API requests:
- `X-Pepperi-OwnerID`: Set to the AddonUUID from addon.config.json.
- `X-Pepperi-SecretKey`: Set to the secret key from var_sk file.

**Multi-Repository Structure Support:**
The server supports different Pepperi repository structures:
- **Simple repos**: Config files at repository root.
- **Complex repos**: Config files in nested directories (e.g., `BackEnd/ADAL/`).
- **Search depth**: Up to 2 directory levels deep.

**Search Algorithm:**
1. Repository root directory.
2. All subdirectories (level 1).
3. All sub-subdirectories (level 2).
4. First matching files are used.


**Performance Optimization:**
- Repository configurations are cached after first load.
- Subsequent API calls to the same repository use cached configuration.
- Eliminates repeated file system searches for better performance.

### Tokens Caching

- Configuration loaded into memory on server startup.
- Tokens cache per environment.
- Cached per user/environment combination.
- Automatic expiration and refresh handling.
- In-memory data is updated and persisted to file on token refresh or new token fetch.
- Cached in OS-appropriate cache directory.
- No re-authentication needed for valid cached tokens.

**Token Cache File Locations:**
- **Windows**: `%APPDATA%\pepperi-api-mcp\token-cache.json`
- **macOS**: `~/Library/Caches/pepperi-api-mcp/token-cache.json`
- **Linux**: `~/.cache/pepperi-api-mcp/token-cache.json`

### API Call History

- All API calls are logged to a history file.
- Each call is stored as a JSON object with comma separation.
- Includes request details (method, URL, body) and response data.
- Useful for debugging and auditing API usage.

**History File Locations:**
- **Windows**: `%APPDATA%\pepperi-api-mcp\api-call-history.json`
- **macOS**: `~/Library/Caches/pepperi-api-mcp/api-call-history.json`
- **Linux**: `~/.cache/pepperi-api-mcp/api-call-history.json`

### Credentials Configuration

- Configuration loaded into memory on server startup.
- Store user credentials with custom aliases for easy reference.
- Manually edit the credentials configuration file to add entries.
- Reference credentials by alias instead of typing username/password repeatedly.
- Automatic validation of required fields (username, password, environment).
- **Note**: Server restart required after manual credential file edits to reload changes.

**Credentials File Locations:**
- **Windows**: `%APPDATA%\pepperi-api-mcp\credentials-config.json`
- **macOS**: `~/Library/Caches/pepperi-api-mcp/credentials-config.json`
- **Linux**: `~/.cache/pepperi-api-mcp/credentials-config.json`

**Example credentials-config.json:**
```json
{
  "my-prod-user": {
    "UserName": "john.doe@company.com",
    "Password": "your-password",
    "Environment": "production"
  },
  "staging-user": {
    "UserName": "jane.smith@company.com",
    "Password": "test-password",
    "Environment": "staging"
  }
}
```

**Usage with aliases:**
- Use the alias as the `username` parameter in API calls.
- The service will automatically lookup and use the stored credentials.

## Configuration Files Behavior

All configuration files follow a consistent loading and persistence pattern:

- **Startup Loading**: Configuration files are loaded into memory when the MCP server starts.
- **Memory Operations**: All lookups and operations work with in-memory data for performance.
- **File Persistence**: 
  - **Token Cache**: Automatically writes to file when tokens are refreshed or new tokens are fetched.
  - **Credentials Config**: Read-only after startup - requires server restart to reload manual edits.
- **Cache Directories**: All config files are stored in OS-appropriate cache directories for proper isolation.

### Development

```bash
# Build the project
npm run build

# Test MCP server with inspector
npm run test-mcp
```

## Future Improvements
- Unit testing.
- Add more statistics to the history file, i.e. request duration, status code, etc.
- Multiple environments aliases (e.i. "staging", "sandbox", "sb", "SB").
- Support polling async calls.
- Support local debugging (local environment).
- Read addon endpoints files (list from addon config, endpoints from the files) and support calling them locally by name.
- Custom predefined calls.
- Replace console.error() with file-based logging system for debug/info messages.

## License

MIT