Enforce TOOLS-based access control with exact tool validation (#3)

* - Enforce TOOLS-based access control with exact tool validation (no wildcards)
- Add AccessControlService (readonly config) and integrate checks in ListTools/CallTool
- Centralize valid tool names from modules
- Require TOOLS env; update envs, compose, mcp.json; docs and tests updated
- Update README.md
- Add test cases for access control

* Fix not found issue for valid-tools file

* docs: document TOOLS environment variable and access control patterns

- Add TOOLS to environment setup section with examples
- Add TOOLS to environment variables table as required
- Add TOOLS verification to configuration check
- Improve Tool Access Control section with clearer documentation
- Add common configuration patterns (read-only, payment, finance)
- Update error handling documentation with better examples
- Enhance security best practices with specific role examples

---------

Co-authored-by: nitish.k <nitish@opn.ooo>

Author: vubonroy

README.md

@@ -68,7 +68,7 @@
 
 ### Prerequisites
 
-- Node.js 20+ 
+- Node.js 20+
 - npm or yarn
 - [Omise Account](https://dashboard.omise.co/) and API keys
 
@@ -96,6 +96,11 @@ export OMISE_ENVIRONMENT=test
 export OMISE_API_VERSION=2019-05-29
 export OMISE_BASE_URL=https://api.omise.co
 export OMISE_VAULT_URL=https://vault.omise.co
+
+# Set tool access control (mandatory)
+export TOOLS=all  # For development only
+# Or for production, specify exact tools:
+# export TOOLS=create_charge,retrieve_charge,list_charges,create_customer
 ```
 
 #### 2.4. Environment-Specific Configuration
@@ -130,6 +135,7 @@ npm run dev
 # Or verify with a simple check
 echo $OMISE_PUBLIC_KEY | grep -q "pkey_" && echo "✅ Public key configured" || echo "❌ Public key missing"
 echo $OMISE_SECRET_KEY | grep -q "skey_" && echo "✅ Secret key configured" || echo "❌ Secret key missing"
+echo $TOOLS | grep -q "." && echo "✅ TOOLS configured: $TOOLS" || echo "❌ TOOLS not set (required)"
 ```
 
 ### 3. Start Development Server
@@ -160,27 +166,27 @@ curl http://localhost:3000/tools
 ```typescript
 // Create a charge
 const charge = await mcpClient.callTool('create_charge', {
-  amount: 10000,        // 100.00 THB (smallest currency unit)
-  currency: 'THB',
-  description: 'Test payment',
-  capture: true
+    amount: 10000,        // 100.00 THB (smallest currency unit)
+    currency: 'THB',
+    description: 'Test payment',
+    capture: true
 });
 
 // Create a customer
 const customer = await mcpClient.callTool('create_customer', {
-  email: 'customer@example.com',
-  description: 'Test customer'
+    email: 'customer@example.com',
+    description: 'Test customer'
 });
 
 // Create a card token
 const token = await mcpClient.callTool('create_token', {
-  card: {
-    name: 'John Doe',
-    number: '4242424242424242',
-    expiration_month: 12,
-    expiration_year: 2025,
-    security_code: '123'
-  }
+    card: {
+        name: 'John Doe',
+        number: '4242424242424242',
+        expiration_month: 12,
+        expiration_year: 2025,
+        security_code: '123'
+    }
 });
 ```
 
@@ -189,15 +195,15 @@ const token = await mcpClient.callTool('create_token', {
 ```typescript
 // Create a schedule
 const schedule = await mcpClient.callTool('create_schedule', {
-  every: 1,
-  period: 'month',
-  start_date: '2024-01-01',
-  charge: {
-    customer: 'cust_123',
-    amount: 5000,
-    currency: 'THB',
-    description: 'Monthly subscription'
-  }
+    every: 1,
+    period: 'month',
+    start_date: '2024-01-01',
+    charge: {
+        customer: 'cust_123',
+        amount: 5000,
+        currency: 'THB',
+        description: 'Monthly subscription'
+    }
 });
 ```
 
@@ -206,20 +212,20 @@ const schedule = await mcpClient.callTool('create_schedule', {
 ```typescript
 // Create a recipient
 const recipient = await mcpClient.callTool('create_recipient', {
-  name: 'John Doe',
-  email: 'john@example.com',
-  type: 'individual',
-  bank_account: {
-    brand: 'bbl',
-    number: '1234567890',
-    name: 'John Doe'
-  }
+    name: 'John Doe',
+    email: 'john@example.com',
+    type: 'individual',
+    bank_account: {
+        brand: 'bbl',
+        number: '1234567890',
+        name: 'John Doe'
+    }
 });
 
 // Execute transfer
 const transfer = await mcpClient.callTool('create_transfer', {
-  amount: 10000,
-  recipient: recipient.id
+    amount: 10000,
+    recipient: recipient.id
 });
 ```
 
@@ -232,6 +238,7 @@ const transfer = await mcpClient.callTool('create_transfer', {
 | `OMISE_PUBLIC_KEY` | Omise public key | ✓ | - |
 | `OMISE_SECRET_KEY` | Omise secret key | ✓ | - |
 | `OMISE_ENVIRONMENT` | Environment (test/production) | ✓ | - |
+| `TOOLS` | Comma-separated list of allowed tools or 'all' | ✓ | - |
 | `PORT` | Server port | - | 3000 |
 | `HOST` | Server host | - | localhost |
 | `LOG_LEVEL` | Log level | - | info |
@@ -425,6 +432,159 @@ docker-compose logs -f
 - **Rate limiting**: API call restrictions
 - **Sensitive data masking**: Hide sensitive information in logs
 - **Environment isolation**: Complete separation of test and production environments
+- **Tool Access Control**: Granular control over which API tools clients can access
+
+### Tool Access Control
+
+The MCP server requires explicit tool access configuration for enhanced security. Each client must specify which Omise API tools they are authorized to use.
+
+#### Configuration
+
+Set the `TOOLS` environment variable (**mandatory**). The server will not start without this configuration.
+
+**Options:**
+- `TOOLS=all` - Full access to all 50 tools (development only, not recommended for production)
+- `TOOLS=tool1,tool2,...` - Comma-separated list of specific tools (recommended for production)
+
+**Common Patterns:**
+- **Read-only access**: `TOOLS=list_charges,retrieve_charge,list_customers,retrieve_customer`
+- **Payment processing**: `TOOLS=create_charge,retrieve_charge,capture_charge,create_customer,create_token`
+- **Finance operations**: `TOOLS=list_charges,retrieve_charge,create_refund,create_transfer`
+
+#### Examples
+
+**Full access (development/testing):**
+```bash
+export TOOLS=all
+docker-compose up
+```
+
+**Read-only access (monitoring/analytics):**
+```bash
+export TOOLS=list_charges,retrieve_charge,list_customers,retrieve_customer
+docker-compose up
+```
+
+**Payment processing only:**
+```bash
+export TOOLS=create_charge,retrieve_charge,capture_charge,create_customer,create_token
+docker-compose up
+```
+
+**Podman with specific tools:**
+```bash
+podman run --rm -i \
+  -e OMISE_PUBLIC_KEY=pkey_test_xxx \
+  -e OMISE_SECRET_KEY=skey_test_xxx \
+  -e OMISE_ENVIRONMENT=test \
+  -e TOOLS=create_charge,list_charges,create_customer \
+  omise-mcp-server:latest
+```
+
+#### Available Tools by Category
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Charges** | `create_charge`, `retrieve_charge`, `list_charges`, `update_charge`, `capture_charge`, `reverse_charge`, `expire_charge` | Payment charge operations |
+| **Customers** | `create_customer`, `retrieve_customer`, `list_customers`, `update_customer`, `destroy_customer` | Customer management |
+| **Cards** | `list_customer_cards`, `retrieve_customer_card`, `update_customer_card`, `destroy_customer_card` | Card management |
+| **Tokens** | `create_token`, `retrieve_token` | Tokenization |
+| **Sources** | `create_source`, `retrieve_source` | Payment sources |
+| **Transfers** | `create_transfer`, `retrieve_transfer`, `list_transfers`, `update_transfer`, `destroy_transfer` | Transfer operations |
+| **Recipients** | `create_recipient`, `retrieve_recipient`, `list_recipients`, `update_recipient`, `destroy_recipient`, `verify_recipient` | Recipient management |
+| **Refunds** | `create_refund`, `retrieve_refund`, `list_refunds` | Refund processing |
+| **Disputes** | `list_disputes`, `retrieve_dispute`, `accept_dispute`, `update_dispute`, `list_dispute_documents`, `retrieve_dispute_document`, `upload_dispute_document`, `destroy_dispute_document` | Dispute handling |
+| **Schedules** | `create_schedule`, `retrieve_schedule`, `list_schedules`, `destroy_schedule`, `list_schedule_occurrences` | Recurring payments |
+| **Events** | `list_events`, `retrieve_event` | Event tracking |
+| **Capabilities** | `retrieve_capability` | Feature verification |
+
+#### Error Handling
+
+The server will **fail to start** if:
+- `TOOLS` environment variable is not set
+- `TOOLS` is empty or contains only whitespace
+- `TOOLS` contains invalid tool names (e.g., `TOOLS=hello,invalid_tool`)
+
+Clients will receive an **authorization error** if:
+- They attempt to call a tool not in their allowed list
+
+**Example Errors:**
+
+```bash
+# Missing TOOLS environment variable
+Error: Missing required environment variable: TOOLS
+Set TOOLS=all for full access, or specify comma-separated tool names.
+Example: TOOLS=create_charge,list_charges,create_customer
+
+# Invalid tool names
+Error: Invalid tool names: hello, invalid_tool
+Valid tools are: create_charge, retrieve_charge, list_charges, ... (50 total)
+Use TOOLS=all for full access.
+```
+
+**Runtime Behavior:**
+
+When `TOOLS` is properly configured:
+- Only authorized tools appear in `list_tools` responses
+- Unauthorized tools are not accessible to clients
+- Access control is enforced at the MCP protocol level
+
+#### Security Best Practices
+
+1. **Principle of Least Privilege**: Only grant access to tools absolutely necessary for the role
+2. **Production Restrictions**: Never use `TOOLS=all` in production - always specify exact tools
+3. **Role-Based Deployment**: Run separate MCP server instances for different user roles:
+   - **Read-Only (Analytics/Support)**: `list_charges,retrieve_charge,list_customers,retrieve_customer`
+   - **Payment Processing (Merchants)**: `create_charge,retrieve_charge,capture_charge,create_customer,create_token`
+   - **Finance Operations**: `list_charges,create_refund,create_transfer,create_recipient`
+   - **Admin (Development/Emergency)**: `all` (use with caution)
+4. **Regular Audits**: Review and document tool access configurations periodically
+5. **Environment Separation**: Use different TOOLS configurations for dev, staging, and production
+6. **Configuration Management**: Store TOOLS settings in environment-specific config files
+
+#### Multiple Client Configurations
+
+Use Cursor's `mcp.json` to configure multiple clients with different access levels:
+
+```json
+{
+  "mcpServers": {
+    "omise-admin": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "OMISE_PUBLIC_KEY=pkey_xxx",
+        "-e", "OMISE_SECRET_KEY=skey_xxx",
+        "-e", "OMISE_ENVIRONMENT=production",
+        "-e", "TOOLS=all",
+        "omise-mcp-server:latest"
+      ]
+    },
+    "omise-readonly": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "OMISE_PUBLIC_KEY=pkey_xxx",
+        "-e", "OMISE_SECRET_KEY=skey_xxx",
+        "-e", "OMISE_ENVIRONMENT=production",
+        "-e", "TOOLS=list_charges,retrieve_charge,list_customers,retrieve_customer",
+        "omise-mcp-server:latest"
+      ]
+    },
+    "omise-payment": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "OMISE_PUBLIC_KEY=pkey_xxx",
+        "-e", "OMISE_SECRET_KEY=skey_xxx",
+        "-e", "OMISE_ENVIRONMENT=production",
+        "-e", "TOOLS=create_charge,retrieve_charge,capture_charge,create_customer,create_token",
+        "omise-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
 
 ### SSL/TLS Configuration
 
@@ -545,13 +705,13 @@ Create a secure card token for payment processing.
 
 **Parameters:**
 - `card` (required): Card information
-  - `name` (required): Cardholder name
-  - `number` (required): Card number
-  - `expiration_month` (required): Expiration month (1-12)
-  - `expiration_year` (required): Expiration year (4 digits)
-  - `city` (optional): Billing address city
-  - `postal_code` (optional): Billing address postal code
-  - `security_code` (optional): Security code (CVV/CVC)
+    - `name` (required): Cardholder name
+    - `number` (required): Card number
+    - `expiration_month` (required): Expiration month (1-12)
+    - `expiration_year` (required): Expiration year (4 digits)
+    - `city` (optional): Billing address city
+    - `postal_code` (optional): Billing address postal code
+    - `security_code` (optional): Security code (CVV/CVC)
 
 ## 🔗 External Links
 

docker-compose.yml

@@ -21,6 +21,7 @@ services:
     environment:
       - NODE_ENV=production
       - PORT=3000
+      - TOOLS=${TOOLS:-all}
       - LOG_LEVEL=info
       - LOG_FORMAT=json
       - OMISE_TIMEOUT=30000