# Postman MCP Server

Model Context Protocol (MCP) server for integrating Postman API with Cursor IDE, enabling automatic migration of API endpoints from .NET controllers to Postman collections.

## 🎯 Features

- ✅ **List Collections**: List all Postman collections in workspace
- ✅ **Get Collection**: Get detailed collection information
- ✅ **Create Collection**: Create new Postman collections
- ✅ **Create Folder**: Create folders to organize requests (with auto-fix validation errors)
- ✅ **Create Request**: Create API requests manually
- ✅ **Update Request**: Update existing requests
- ✅ **Delete Request**: Delete requests by ID or name (with recursive search)
- ✅ **Sync from Controller**: Automatically parse .NET controller code and migrate endpoints to Postman

## 📋 Requirements

- Node.js >= 18.0.0
- Postman API Key ([Get from Postman Account Settings](https://web.postman.co/settings/me/api-keys))
- Cursor IDE with MCP support

## 🚀 Quick Start

### Step 1: Install Dependencies

```bash
cd .cursor/mcp-servers/postman
npm install
```

### Step 2: Build Project

```bash
npm run build
```

Or use the setup script:

```bash
./setup.sh
```

### Step 3: Get Postman API Key

1. Go to [Postman Account Settings](https://web.postman.co/settings/me/api-keys)
2. Create or copy your API Key (format: `PMAK-xxxxx-xxxxx`)

### Step 4: Configure Cursor MCP Settings

Add to Cursor MCP configuration (usually in `~/.cursor/mcp.json` or Cursor Settings):

**macOS - Get absolute path:**
```bash
cd .cursor/mcp-servers/postman
./get-path.sh
# Script will copy path to clipboard
```

**Configuration:**
```json
{
  "mcpServers": {
    "postman": {
      "command": "node",
      "args": ["/absolute/path/to/.cursor/mcp-servers/postman/dist/index.js"],
      "env": {
        "POSTMAN_API_KEY": "your-postman-api-key-here"
      }
    }
  }
}
```

**Example for macOS:**
```json
{
  "mcpServers": {
    "postman": {
      "command": "node",
      "args": ["/Users/dangvietson/Desktop/feec-phase1-pm/feec-phase1-pmsystem/.cursor/mcp-servers/postman/dist/index.js"],
      "env": {
        "POSTMAN_API_KEY": "PMAK-xxxxx-xxxxx-xxxxx"
      }
    }
  }
}
```

**Note**: Replace `/absolute/path/to/` with your actual absolute path.

### Step 5: Restart Cursor IDE

1. **Quit Cursor completely** (`Cmd + Q` on macOS)
2. **Reopen Cursor**
3. **Test**: Type "List all Postman collections" in Cursor chat

## 📖 Usage Examples

### 1. List Collections

```
List all Postman collections
```

### 2. Create Collection

```
Create a new Postman collection named "FEEC PM System APIs" with description "Project Management System API endpoints"
```

### 3. Create Folder

```
Create folder "API V1" with description "Version 1.0 endpoints" in Postman collection 97f3e1da-a4e9-44f6-8d1a-83766a827e54
```

### 4. Create Request Manually

```
Create a new GET request in collection 97f3e1da-a4e9-44f6-8d1a-83766a827e54:
- Name: "Get User by ID"
- Method: GET
- URL: {{baseUrl}}/api/v1/users/{userId}
- Headers: Content-Type: application/json
- Description: Retrieve user details by ID
```

### 5. Auto-Sync from Controller (Recommended)

Use the custom command `/migrate-endpoint-to-postman` or manually:

```
Sync API endpoints from this controller code to Postman collection 97f3e1da-a4e9-44f6-8d1a-83766a827e54:

[Paste full C# controller code here]

Base URL: http://localhost:5020
API Version: 1.0
Folder: PM System API V1
```

The server will automatically:
- Parse all HTTP endpoints (`[HttpGet]`, `[HttpPost]`, etc.)
- Extract routes from `[Route]` attributes
- Extract API version from `[ApiVersion]` attributes
- Extract XML comments for descriptions
- Extract API Code and Screen ID from comments
- Generate request names: `{API Code} - {API Name}`
- Generate request bodies for POST/PUT/PATCH
- Handle path parameters (`{id:guid}` → `:id`)
- Handle query parameters (`[FromQuery]`)
- Expand `PagedRequest` into `pageNumber`, `pageSize`, `searchTerm`
- Add Authorization header only if `[Authorize]` attribute is present

### 6. Delete Request

```
Delete request "Test API Request" from Postman collection PMSystem
```

Or by ID:
```
Delete request with ID 8ea7c1f4-c9ba-4293-bbf4-b037f7962854 from collection 97f3e1da-a4e9-44f6-8d1a-83766a827e54
```

## 🔧 API Reference

### Tool: `list_collections`
- **Description**: List all Postman collections
- **Parameters**: None
- **Returns**: Array of collections with `id`, `name`, `uid`

### Tool: `get_collection`
- **Description**: Get detailed collection information
- **Parameters**: 
  - `collectionId` (string, required): Collection ID (UID)
- **Returns**: Full collection object with items, variables, etc.

### Tool: `create_collection`
- **Description**: Create new Postman collection
- **Parameters**:
  - `name` (string, required): Collection name
  - `description` (string, optional): Collection description
- **Returns**: Created collection object

### Tool: `create_folder`
- **Description**: Create folder in collection to organize requests
- **Parameters**:
  - `collectionId` (string, required): Collection ID
  - `name` (string, required): Folder name
  - `description` (string, optional): Folder description
- **Returns**: Updated collection object
- **Features**:
  - Auto-fixes invalid collection variables (type validation)
  - Creates folder with placeholder request (avoids empty folder validation error)
  - Preserves entire collection structure

### Tool: `create_request`
- **Description**: Create API request in collection
- **Parameters**:
  - `collectionId` (string, required): Collection ID
  - `name` (string, required): Request name
  - `method` (string, required): HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
  - `url` (string, required): Full URL or path
  - `headers` (object, optional): HTTP headers as key-value pairs
  - `body` (object, optional): Request body for POST/PUT/PATCH
    - `mode`: "raw", "urlencoded", "formdata"
    - `raw`: JSON string for raw body
  - `description` (string, optional): Request description
  - `folderId` (string, optional): Folder ID to organize requests
- **Returns**: Updated collection object

### Tool: `update_request`
- **Description**: Update existing request
- **Parameters**:
  - `collectionId` (string, required): Collection ID
  - `requestId` (string, required): Request ID (UID) to update
  - `name`, `method`, `url`, `headers`, `body`, `description` (optional): Fields to update
- **Returns**: Updated collection object

### Tool: `delete_request`
- **Description**: Delete API request from collection
- **Parameters**:
  - `collectionId` (string, required): Collection ID
  - `requestId` (string, optional): Request ID (UID) to delete
  - `requestName` (string, optional): Request name to find and delete
- **Returns**: Updated collection object
- **Features**:
  - Delete by ID or name
  - Recursive search in folders
  - Auto-fixes collection variables
  - Preserves collection structure

### Tool: `sync_from_controller`
- **Description**: Automatically migrate endpoints from .NET controller code
- **Parameters**:
  - `collectionId` (string, required): Postman collection ID
  - `controllerCode` (string, required): Full C# controller code with XML comments
  - `baseUrl` (string, required): Base URL (e.g., `http://localhost:5020`)
  - `apiVersion` (string, optional): API version (default: "1.0")
  - `folderName` (string, optional): Folder name to organize requests (will be created if not exists)
- **Returns**: Summary of created requests with endpoint details
- **Features**:
  - Parses `[Route]`, `[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]` attributes
  - Extracts XML comments (`/// <summary>`, `API Code:`, `Screen ID:`)
  - Generates request names: `{API Code} - {API Name}` (from summary)
  - Generates request bodies from DTO properties
  - Handles path parameters (`{id:guid}` → `:id` Postman format)
  - Handles query parameters (`[FromQuery]`)
  - Expands `PagedRequest` into individual query parameters
  - Adds Authorization header only if `[Authorize]` attribute is present
  - Replaces `[controller]` placeholder with actual controller name
  - Extracts major version from API version (e.g., "1.0" → "v1")
  - Uses `{{baseUrl}}` Postman variable for URLs

## 🎨 Controller Code Requirements

For `sync_from_controller` to work optimally:

- ✅ Controller must have `[ApiController]` attribute
- ✅ Methods must have HTTP method attributes (`[HttpGet]`, `[HttpPost]`, etc.)
- ✅ XML comments with `/// <summary>` for descriptions
- ✅ `API Code: XXXX` in comments for request naming
- ✅ `Screen ID: XXXX` in comments (optional)

**Example:**
```csharp
/// <summary>
/// Get vendor quotation history for specified vendors within a specific ES Version (v1.0)
/// API Code: QS0041
/// Screen ID: QS-L0004-2 (Estimation quotation vendor history)
/// </summary>
[HttpGet("quotation-history")]
public async Task<IActionResult> GetVendorQuotationHistory(
    [FromQuery] Guid versionId,
    [FromQuery(Name = "vendorId")] List<Guid> vendorIds,
    CancellationToken cancellationToken)
{
    // Implementation...
}
```

**Generated Request:**
- **Name**: `QS0041 - Get vendor quotation history for specified vendors within a specific ES Version`
- **URL**: `{{baseUrl}}/api/v1/Vendors/quotation-history?versionId=...&vendorId=...`
- **Method**: GET
- **Headers**: Only Authorization if `[Authorize]` is present

## 🔄 Development Workflow

### Workflow 1: Manual Migration (Step-by-step)

1. **Create Collection** for each system (PM, DC, ES, QS, Master)
2. **Develop API** in .NET controller
3. **Create Request** in Postman via Cursor prompt
4. **Test** in Postman

### Workflow 2: Auto-Sync (Bulk Migration) ⭐ Recommended

1. **Develop API** in .NET controller with complete XML comments
2. **Use `/migrate-endpoint-to-postman` command** or sync manually
3. **Verify** in Postman
4. **Update** if needed

### Workflow 3: GitHub Actions Integration (Future)

Create GitHub Action workflow to auto-sync when PR is merged:

```yaml
name: Sync APIs to Postman

on:
  pull_request:
    types: [closed]

jobs:
  sync-postman:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: |
          # Parse changed controllers
          # Call Postman MCP Server
          # Create/update requests
```

## 🔐 Security Notes

- **API Key**: Do not commit `POSTMAN_API_KEY` to git (already in `.gitignore`)
- **Local Only**: Server runs locally, not exposed externally
- **Environment Variables**: Use `.env` file if needed (do not commit)

## 🐛 Troubleshooting

### Server Not Starting

- Check Node.js version: `node --version` (requires >= 18)
- Check build: `npm run build`
- Check absolute path in MCP config (must be absolute path)
- **After code changes**: Quit Cursor completely and rebuild with `npm run build`

### Postman API Errors

- Verify API Key: Check key format (`PMAK-...`)
- Check API limits: Postman has rate limits
- Verify Collection ID: Collection ID must be UID (not name)
- Check workspace permissions: Need Editor or Admin role

### Endpoints Not Parsed

- Ensure controller code has complete attributes
- Check XML comments format (must use `///`)
- Verify route patterns
- Check for `[ApiController]` attribute

### Request Names Not Correct

- Ensure `API Code: XXXX` is present in XML comments
- Check summary format in `<summary>` tags
- Rebuild MCP server after code changes: `npm run build`

### Headers Not Added

- Authorization header is only added when `[Authorize]` attribute is explicitly present
- No default headers (X-API-Version, Accept, Content-Type) are added automatically
- Headers are only added when explicitly defined in code (e.g., `[FromHeader]` parameters)

## 📁 Project Structure

```
.cursor/mcp-servers/postman/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── controller-parser.ts  # .NET controller parser
├── dist/                     # Compiled JavaScript (after build)
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md                 # This file
├── get-path.sh              # Helper script to get absolute path
├── setup.sh                 # Setup script
└── rebuild-after-quit.sh    # Rebuild script after quitting Cursor
```

## 🛠️ Development

### Run in Development Mode

```bash
npm run dev
```

### Type Check

```bash
npm run type-check
```

### Build

```bash
npm run build
```

**Important**: After making code changes, you must:
1. Quit Cursor completely
2. Run `npm run build`
3. Reopen Cursor

Or use the helper script:
```bash
./rebuild-after-quit.sh
```

## 📚 References

- [Postman API Documentation](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52c667e1afe6)
- [MCP SDK Documentation](https://modelcontextprotocol.io/)
- [Cursor MCP Setup](https://docs.cursor.com/mcp)

## 🗺️ Roadmap

### ✅ Completed Features

- [x] List collections
- [x] Get collection details
- [x] Create collection
- [x] Create folder (with auto-fix validation errors)
- [x] Create request
- [x] Update request
- [x] Delete request (by ID or name, recursive search)
- [x] Sync from .NET controller (parse routes, methods, parameters)
- [x] Extract XML comments (summary, API Code, Screen ID)
- [x] Generate request names: `{API Code} - {API Name}`
- [x] Handle path/query parameters
- [x] Expand `PagedRequest` into individual parameters
- [x] Authorization header based on `[Authorize]` attribute
- [x] No default headers (only explicit headers from code)

### 🔄 Planned Enhancements

#### Phase 1: Enhanced Parsing
- [ ] Support for `[FromForm]` parameters (multipart/form-data)
- [ ] Support for `[FromHeader]` parameters (already parsed, need to add to headers)
- [ ] Better DTO property type detection
- [ ] Support for nested DTOs
- [ ] Extract validation rules from FluentValidation

#### Phase 2: Advanced Features
- [ ] Update existing requests (detect changes and update)
- [ ] Delete deprecated endpoints
- [ ] Support for multiple API versions in same collection
- [ ] Generate Postman tests from controller code
- [ ] Support for authentication (JWT, API Key, etc.)

#### Phase 3: Integration
- [ ] GitHub Actions integration (auto-sync on PR merge)
- [ ] Support for other frameworks (FastAPI, Express.js, etc.)
- [ ] Export collection to OpenAPI/Swagger
- [ ] Import from OpenAPI/Swagger

## 📝 Best Practices

1. **Naming**: Use API Code in XML comments for consistent naming
2. **Organization**: Create folders by system/version for easy management
3. **Documentation**: Add descriptions for requests for better understanding
4. **Testing**: Test requests after migration to ensure correctness
5. **Authorization**: Use `[Authorize]` attribute explicitly when authentication is required
6. **Headers**: Only add headers when explicitly defined in code

## 🤝 Contributing

When adding new features:
1. Update this README with new features
2. Test thoroughly
3. Update roadmap section
4. Rebuild and test in Cursor

---

**Last Updated**: 2026-01-23  
**Version**: 1.0.0  
**Status**: ✅ Production Ready