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

{
  "my-prod-user": {
    "UserName": "[email protected]",
    "Password": "your-password",
    "Environment": "production"
  },
  "staging-user": {
    "UserName": "[email protected]",
    "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").
• 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