@pepperi-addons/api-mcp

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

npm install -g @pepperi-addons/api-mcp

Local Installation

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):

{
  "mcpServers": {
    "pepperi-api": {
      "command": "npx",
      "args": ["@pepperi-addons/api-mcp@latest"]
    }
  }
}

For Global Installation:

{
  "mcpServers": {
    "pepperi-api": {
      "command": "pepperi-api-mcp",
      "args": []
    }
  }
}

For Local Installation:

{
  "mcpServers": {
    "pepperi-api": {
      "command": "node",
      "args": ["./node_modules/@pepperi-addons/api-mcp/dist/pepperi-api-mcp.server.js"]
    }
  }
}

For Development/Testing:

{
  "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)

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)

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:

{
  "my-prod-user": {
    "UserName": "[e-mail]",
    "Password": "your-password",
    "Environment": "production"
  },
  "staging-user": {
    "UserName": "[e-mail]",
    "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

# 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").
• Read secret key & addon UUID from addons and send in the header.
• 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