# Directory Structure
```
├── .eslintrc.json
├── .github
│ ├── dependabot.yml
│ ├── pull_request_template.md
│ └── workflows
│ └── ci.yml
├── .gitignore
├── .husky
│ └── pre-commit
├── .npmignore
├── build
│ ├── index.d.ts
│ ├── index.js
│ ├── index.js.map
│ ├── newman
│ │ ├── runner.d.ts
│ │ ├── runner.js
│ │ └── runner.js.map
│ └── server
│ ├── server.d.ts
│ ├── server.js
│ ├── server.js.map
│ ├── types.d.ts
│ ├── types.js
│ └── types.js.map
├── CONTRIBUTING.md
├── Dockerfile
├── example
│ ├── .eslintrc.json
│ ├── postman
│ │ ├── collection.json
│ │ └── environment.json
│ ├── prompts
│ │ └── CODING_STANDARDS.md
│ ├── src
│ │ └── server.ts
│ └── tsconfig.json
├── LICENSE
├── package.json
├── pnpm-lock.yaml
├── prompts
│ ├── MCP_REFERENCE_DOCS.md
│ ├── POSTMAN_NEWMAN_REFERENCE_DOCS.md
│ ├── STEP_1_INITIAL_CODE_IMPLEMENTATION.md
│ ├── STEP_2_FIX_BROKEN_UNIT_TEST.md
│ └── STEP_3_EXAMPLE_API.md
├── README.md
├── smithery.yaml
├── src
│ ├── index.ts
│ ├── newman
│ │ └── runner.ts
│ └── server
│ ├── server.ts
│ └── types.ts
├── test
│ ├── fixtures
│ │ └── sample-collection.json
│ ├── newman-runner.test.ts
│ └── server.test.ts
├── tsconfig.json
├── tsconfig.test.json
└── vitest.config.ts
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
node_modules
```
--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
```
# Source files
src/
example/
test/
# Configuration files
.eslintrc.json
tsconfig.json
tsconfig.test.json
vitest.config.ts
# Development files
.husky/
.github/
prompts/
# Documentation
docs/
*.md
!README.md
# Git files
.git/
.gitignore
# IDE files
.vscode/
.idea/
# Test coverage
coverage/
# Lock files
pnpm-lock.yaml
```
--------------------------------------------------------------------------------
/example/.eslintrc.json:
--------------------------------------------------------------------------------
```json
{
"extends": [
"eslint:recommended",
"plugin:@typescript-eslint/recommended"
],
"parser": "@typescript-eslint/parser",
"parserOptions": {
"project": "./example/tsconfig.json",
"ecmaVersion": 2020,
"sourceType": "module"
},
"plugins": [
"@typescript-eslint"
],
"root": true,
"ignorePatterns": ["dist/"]
}
```
--------------------------------------------------------------------------------
/.eslintrc.json:
--------------------------------------------------------------------------------
```json
{
"env": {
"node": true,
"es2022": true
},
"extends": [
"eslint:recommended",
"plugin:@typescript-eslint/recommended",
"plugin:@typescript-eslint/recommended-requiring-type-checking",
"prettier"
],
"parser": "@typescript-eslint/parser",
"parserOptions": {
"ecmaVersion": "latest",
"sourceType": "module",
"project": ["./tsconfig.json", "./tsconfig.test.json"]
},
"plugins": ["@typescript-eslint"],
"rules": {
"@typescript-eslint/explicit-function-return-type": "error",
"@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
"@typescript-eslint/no-explicit-any": "error",
"@typescript-eslint/no-floating-promises": "error",
"@typescript-eslint/no-misused-promises": ["error", {
"checksVoidReturn": {
"arguments": false
}
}],
"no-console": ["error", { "allow": ["warn", "error"] }],
"@typescript-eslint/require-await": "warn"
},
"ignorePatterns": ["build/", "coverage/", "*.js"]
}
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# Postman MCP Server
[](https://smithery.ai/server/mcp-postman)
An MCP (Model Context Protocol) server that enables running Postman collections using Newman. This server allows LLMs to execute API tests and get detailed results through a standardized interface.
[](https://youtu.be/d1WgTqwMsog)
<a href="https://glama.ai/mcp/servers/qfx34b2s2v"><img width="380" height="200" src="https://glama.ai/mcp/servers/qfx34b2s2v/badge" alt="Postman Server MCP server" /></a>
## Features
- Run Postman collections using Newman
- Support for environment files
- Support for global variables
- Detailed test results including:
- Overall success/failure status
- Test summary (total, passed, failed)
- Detailed failure information
- Execution timings
## Installation
### Installing via Smithery
To install Postman Runner for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-postman):
```bash
npx -y @smithery/cli install mcp-postman --client claude
```
### Manual Installation
```bash
# Clone the repository
git clone <repository-url>
cd mcp-postman
# Install dependencies
pnpm install
# Build the project
pnpm build
```
## Usage
### Configuration
Add the server to your Claude desktop configuration file at `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"postman-runner": {
"command": "node",
"args": ["/absolute/path/to/mcp-postman/build/index.js"]
}
}
}
```
### Available Tools
#### run-collection
Runs a Postman collection and returns the test results.
**Parameters:**
- `collection` (required): Path or URL to the Postman collection
- `environment` (optional): Path or URL to environment file
- `globals` (optional): Path or URL to globals file
- `iterationCount` (optional): Number of iterations to run
**Example Response:**
```json
{
"success": true,
"summary": {
"total": 5,
"failed": 0,
"passed": 5
},
"failures": [],
"timings": {
"started": "2024-03-14T10:00:00.000Z",
"completed": "2024-03-14T10:00:01.000Z",
"duration": 1000
}
}
```
### Example Usage in Claude
You can use the server in Claude by asking it to run a Postman collection:
"Run the Postman collection at /path/to/collection.json and tell me if all tests passed"
Claude will:
1. Use the run-collection tool
2. Analyze the test results
3. Provide a human-friendly summary of the execution
## Development
### Project Structure
```
src/
├── index.ts # Entry point
├── server/
│ ├── server.ts # MCP Server implementation
│ └── types.ts # Type definitions
└── newman/
└── runner.ts # Newman runner implementation
test/
├── server.test.ts # Server tests
├── newman-runner.test.ts # Runner tests
└── fixtures/ # Test fixtures
└── sample-collection.json
```
### Running Tests
```bash
# Run tests
pnpm test
# Run tests with coverage
pnpm test:coverage
```
### Building
```bash
# Build the project
pnpm build
# Clean build artifacts
pnpm clean
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
ISC
```
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
# Contributing to MCP Postman Server
We love your input! We want to make contributing to MCP Postman Server as easy and transparent as possible, whether it's:
- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Proposing new features
- Becoming a maintainer
## We Develop with GitHub
We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html)
Pull requests are the best way to propose changes to the codebase. We actively welcome your pull requests:
1. Fork the repo and create your branch from `main`.
2. If you've added code that should be tested, add tests.
3. If you've changed APIs, update the documentation.
4. Ensure the test suite passes.
5. Make sure your code lints.
6. Issue that pull request!
## Any contributions you make will be under the MIT Software License
In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
## Report bugs using GitHub's issue tracker
We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy!
## Write bug reports with detail, background, and sample code
**Great Bug Reports** tend to have:
- A quick summary and/or background
- Steps to reproduce
- Be specific!
- Give sample code if you can.
- What you expected would happen
- What actually happens
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
## Use a Consistent Coding Style
- Use 2 spaces for indentation rather than tabs
- Use TypeScript types and interfaces
- Keep line length to 100 characters or less
- Write JSDoc comments for functions and classes
- Follow the project's ESLint configuration
## License
By contributing, you agree that your contributions will be licensed under its MIT License.
```
--------------------------------------------------------------------------------
/tsconfig.test.json:
--------------------------------------------------------------------------------
```json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"rootDir": "."
},
"include": ["test/**/*", "vitest.config.ts"],
"exclude": ["node_modules", "build"]
}
```
--------------------------------------------------------------------------------
/example/postman/environment.json:
--------------------------------------------------------------------------------
```json
{
"name": "Example API Environment",
"values": [
{
"key": "baseUrl",
"value": "http://localhost:3000",
"type": "default",
"enabled": true
}
]
}
```
--------------------------------------------------------------------------------
/.github/dependabot.yml:
--------------------------------------------------------------------------------
```yaml
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
versioning-strategy: "auto"
labels:
- "dependencies"
- "npm"
commit-message:
prefix: "chore"
include: "scope"
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
startCommand:
type: stdio
configSchema:
# JSON Schema defining the configuration options for the MCP.
type: object
properties: {}
commandFunction:
# A function that produces the CLI command to start the MCP on stdio.
|-
(config) => ({command: 'node', args: ['build/index.js']})
```
--------------------------------------------------------------------------------
/vitest.config.ts:
--------------------------------------------------------------------------------
```typescript
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
globals: true,
environment: 'node',
include: ['test/**/*.test.ts'],
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'node_modules/**',
'build/**',
'test/**',
'**/*.test.ts',
'vitest.config.ts'
]
}
}
})
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"declaration": true,
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "build", "test"]
}
```
--------------------------------------------------------------------------------
/example/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2020",
"module": "ES2020",
"lib": ["ES2020"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "node",
"resolveJsonModule": true,
"baseUrl": "..",
"paths": {
"*": ["node_modules/*"]
}
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
# Use a Node.js image
FROM node:18-alpine AS builder
# Install pnpm
RUN npm install -g pnpm
# Set the working directory
WORKDIR /app
# Copy package.json and pnpm-lock.yaml to leverage Docker cache for dependencies
COPY package.json pnpm-lock.yaml ./
# Install dependencies
RUN pnpm install
# Copy the source code
COPY src ./src
COPY tsconfig.json ./
# Build the project
RUN pnpm build
# Use a smaller Node.js image for running the application
FROM node:18-alpine
# Set the working directory
WORKDIR /app
# Copy the built files and package.json
COPY --from=builder /app/build ./build
COPY --from=builder /app/package.json ./
# Install only production dependencies
RUN pnpm install --prod
# Set the entry point for the application
ENTRYPOINT ["node", "build/index.js"]
```
--------------------------------------------------------------------------------
/.github/pull_request_template.md:
--------------------------------------------------------------------------------
```markdown
## Description
<!-- Provide a brief description of the changes in this PR -->
## Type of Change
<!-- Mark the appropriate option with an 'x' -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Other (please describe):
## Checklist
<!-- Mark completed items with an 'x' -->
- [ ] I have read the [CONTRIBUTING](../CONTRIBUTING.md) document
- [ ] My code follows the code style of this project
- [ ] I have added/updated documentation as needed
- [ ] I have added tests that prove my fix/feature works
- [ ] All new and existing tests pass
- [ ] I have tested these changes locally
## Additional Notes
<!-- Add any additional notes, context, or screenshots about the PR here -->
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { PostmanServer } from "./server/server.js";
async function main(): Promise<void> {
try {
const postmanServer = new PostmanServer();
const server = await postmanServer.start();
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Postman MCP Server running on stdio");
// Handle cleanup on exit
process.on('SIGINT', async () => {
await server.close();
process.exit(0);
});
process.on('SIGTERM', async () => {
await server.close();
process.exit(0);
});
} catch (error) {
console.error("Fatal error in main():", error);
process.exit(1);
}
}
void main();
```
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
```yaml
name: CI
run-name: ${{ github.actor }} triggered CI workflow
on:
pull_request:
jobs:
main:
name: Lint and Test
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup PNPM
uses: pnpm/action-setup@v4
with:
version: 8.15.4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "18.19.0"
cache: "pnpm"
cache-dependency-path: "pnpm-lock.yaml"
- name: Verify lockfile
run: |
if [ ! -f "pnpm-lock.yaml" ]; then
echo "pnpm-lock.yaml not found!"
exit 1
fi
echo "pnpm-lock.yaml found"
cat pnpm-lock.yaml
- name: Install dependencies
run: pnpm install
- name: Run ESLint
run: pnpm lint
- name: Run Tests
run: pnpm test:ci
```
--------------------------------------------------------------------------------
/src/server/types.ts:
--------------------------------------------------------------------------------
```typescript
// Types for Newman runner input
export interface CollectionRunOptions {
collection: string; // Path or URL to Postman collection
environment?: string; // Optional path or URL to environment file
globals?: string; // Optional path or URL to globals file
iterationCount?: number; // Optional number of iterations to run
}
// Types for test results
export interface TestSummary {
total: number;
failed: number;
passed: number;
}
export interface TestFailure {
name: string;
error: string;
request: {
method: string;
url: string;
};
}
export interface TestTimings {
started: string;
completed: string;
duration: number;
}
export interface TestResult {
success: boolean;
summary: TestSummary;
failures: TestFailure[];
timings: TestTimings;
}
// MCP Tool response type
export interface McpToolResponse {
content: [{
type: "text";
text: string;
}];
}
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "mcp-postman",
"version": "1.0.2",
"description": "MCP Server for running Postman collections using Newman",
"main": "build/index.js",
"type": "module",
"bin": {
"mcp-postman": "./build/index.js"
},
"scripts": {
"build": "tsc && chmod +x build/index.js",
"test": "vitest",
"test:ci": "vitest run",
"test:coverage": "vitest run --coverage",
"lint": "eslint . --ext .ts",
"format": "prettier --write \"src/**/*.ts\"",
"clean": "rm -rf build",
"prepare": "husky",
"example:dev": "cross-env NODE_OPTIONS=\"--loader ts-node/esm\" ts-node --watch example/src/server.ts",
"example:nodemon": "cross-env NODE_OPTIONS=\"--loader ts-node/esm\" nodemon --watch example example/src/server.ts",
"example:build": "tsc -p example/tsconfig.json"
},
"lint-staged": {
"*.ts": [
"prettier --write",
"eslint --fix",
"vitest related --run"
]
},
"keywords": [
"mcp",
"postman",
"newman",
"api-testing"
],
"author": "",
"license": "ISC",
"dependencies": {
"@modelcontextprotocol/sdk": "latest",
"newman": "^6.0.0",
"zod": "^3.22.4"
},
"devDependencies": {
"@types/express": "^4.17.21",
"@types/newman": "^5.3.0",
"@types/node": "^20.0.0",
"@typescript-eslint/eslint-plugin": "^6.0.0",
"@typescript-eslint/parser": "^6.0.0",
"@vitest/coverage-v8": "^1.0.0",
"axios": "^1.7.9",
"cross-env": "^7.0.3",
"eslint": "^8.0.0",
"eslint-config-prettier": "^9.0.0",
"express": "^4.18.2",
"husky": "^9.1.7",
"lint-staged": "^15.3.0",
"nodemon":"3.1.9",
"prettier": "^3.0.0",
"ts-node": "^10.9.0",
"typescript": "^5.0.0",
"vitest": "^1.0.0"
}
}
```
--------------------------------------------------------------------------------
/prompts/STEP_2_FIX_BROKEN_UNIT_TEST.md:
--------------------------------------------------------------------------------
```markdown
After analyzing both the server implementation and test file, here are the key test scenarios that should be covered for the PostmanServer class:
Server Initialization Tests:
Server should be properly initialized with correct name and version
NewmanRunner should be instantiated
Tools should be properly registered during setup
Tool Listing Tests:
Should list exactly one tool named "run-collection"
Tool description should be present
Input schema should correctly specify required and optional parameters:
collection (required, string)
environment (optional, string)
globals (optional, string)
iterationCount (optional, number)
Collection Running Tests:
Successful collection run with minimal parameters (just collection path)
Successful collection run with all optional parameters
Error handling for invalid collection path
Error handling for invalid environment file
Error handling for invalid globals file
Error handling for invalid iterationCount (less than 1)
Input Validation Tests:
Should reject when collection parameter is missing
Should reject when iterationCount is less than 1
Should reject when unknown tool name is provided
Should handle invalid input types (e.g., number for collection path)
Response Format Tests:
Successful response should have correct structure with content array
Error response should have isError flag and proper error message
Response should properly stringify Newman runner results
Response should maintain proper JSON-RPC 2.0 format
Looking at the current test file:
Most tests are commented out
The only active test is a basic initialization test
The mock transport setup is commented out, which is needed for proper MCP server testing
The NewmanRunner mock is set up but not fully utilized
The test file needs to be fixed by:
Implementing proper transport mocking
Uncommenting and fixing the existing tests
Adding missing test cases for complete coverage
Ensuring proper error handling tests
Adding validation for all optional parameters
Would you like me to proceed with implementing these test cases?
```
--------------------------------------------------------------------------------
/prompts/STEP_3_EXAMPLE_API.md:
--------------------------------------------------------------------------------
```markdown
Implementation Plan for Sample Express Server with Postman Tests:
Dependencies Required (devDependencies):
{
"devDependencies": {
"@types/express": "^4.17.x",
"@types/node": "^20.x.x",
"express": "^4.18.x",
"typescript": "^5.x.x"
}
}
Example Directory Structure:
example/
├── src/
│ └── server.ts # Express server implementation
├── postman/
│ ├── collection.json # Postman collection file
│ └── environment.json # Postman environment file
├── package.json # Project dependencies
└── tsconfig.json # TypeScript configuration
Server Implementation Plan (server.ts):
Create an Express server with two endpoints:
GET /api/items - Returns a list of sample items
POST /api/items - Accepts a new item and returns the created item
Server will run on port 3000
Include proper TypeScript types for request/response objects
Implement basic error handling
Add request logging middleware
Postman Environment (environment.json):
{
"name": "Sample API Environment",
"values": [
{
"key": "baseUrl",
"value": "http://localhost:3000",
"type": "default",
"enabled": true
}
]
}
Postman Collection Plan (collection.json):
Collection Name: "Sample API Tests"
Two request folders:
GET Requests
Test endpoint: GET {{baseUrl}}/api/items
Tests to verify:
Status code is 200
Response is an array
Response time is acceptable
POST Requests
Test endpoint: POST {{baseUrl}}/api/items
Request body: JSON object with item details
Tests to verify:
Status code is 201
Response contains created item
Response matches request schema
Additional Considerations:
Error Handling:
Implement proper HTTP status codes
Return meaningful error messages
Add request validation
TypeScript Types:
Define interfaces for request/response objects
Use proper type annotations
Ensure strict type checking
Testing Strategy:
Collection will include pre-request scripts
Environment variables for configuration
Test assertions for each endpoint
Response schema validation
Documentation:
Add API documentation in collection
Include example requests/responses
Document environment setup
This implementation plan provides a structured approach to creating a sample Express server with Postman tests while maintaining TypeScript best practices and proper testing coverage.
```
--------------------------------------------------------------------------------
/example/src/server.ts:
--------------------------------------------------------------------------------
```typescript
import express, {
type Request,
type Response,
type NextFunction,
} from "express";
import axios from "axios";
// Types for CoinDesk API
interface CoinDeskTime {
updated: string;
updatedISO: string;
updateduk: string;
}
interface CoinDeskCurrency {
code: string;
symbol: string;
rate: string;
description: string;
rate_float: number;
}
interface CoinDeskBPI {
USD: CoinDeskCurrency;
GBP: CoinDeskCurrency;
EUR: CoinDeskCurrency;
}
interface CoinDeskResponse {
time: CoinDeskTime;
disclaimer: string;
chartName: string;
bpi: CoinDeskBPI;
}
// Types for our API
interface Item {
id: string;
name: string;
description: string;
createdAt: string;
}
interface CreateItemRequest {
name: string;
description: string;
}
// In-memory storage for items
const items: Item[] = [];
const app = express();
const PORT = 3000;
// Middleware
app.use(express.json());
app.use((req: Request, _res: Response, next: NextFunction) => {
console.log(`${new Date().toISOString()} - ${req.method} ${req.path}`);
next();
});
// GET /api/items - Get all items
app.get("/api/items", (_req: Request, res: Response) => {
res.json(items);
});
// POST /api/items - Create a new item
app.post("/api/items", (req: Request, res: Response) => {
const { name, description } = req.body as CreateItemRequest;
// Validate request body
if (!name || !description) {
return res.status(400).json({ error: "Name and description are required" });
}
const newItem: Item = {
id: Date.now().toString(),
name,
description,
createdAt: new Date().toISOString(),
};
items.push(newItem);
res.status(201).json(newItem);
});
// Start server
app.listen(PORT, () => {
console.log(`Server is running on http://localhost:${PORT}`);
});
// GET /api/currentprice - Get current Bitcoin price
app.get("/api/currentprice", async (_req: Request, res: Response) => {
try {
const response = await axios.get<CoinDeskResponse>(
"https://api.coindesk.com/v1/bpi/currentprice.json",
);
res.status(200).json(response.data);
} catch (error) {
res.status(500).json({ error: "Failed to fetch Bitcoin price data" });
}
});
// Error handling middleware
app.use((err: Error, _req: Request, res: Response) => {
console.error(err.stack);
res.status(500).json({ error: "Something went wrong!" });
});
export default app;
```
--------------------------------------------------------------------------------
/src/newman/runner.ts:
--------------------------------------------------------------------------------
```typescript
import newman, { NewmanRunFailure } from 'newman';
import { CollectionRunOptions, TestResult, TestFailure } from '../server/types.js';
/**
* Safely extracts test failure information from a Newman failure object
*/
function extractFailureInfo(failure: NewmanRunFailure): TestFailure | null {
try {
if (!failure.error || !failure.source?.request) {
return null;
}
const { error, source } = failure;
const { request } = source;
// Ensure we have all required properties
if (!error.test || !error.message || !request.method || !request.url) {
return null;
}
return {
name: error.test,
error: error.message,
request: {
method: request.method,
url: request.url.toString()
}
};
} catch {
return null;
}
}
export class NewmanRunner {
/**
* Runs a Postman collection using Newman
* @param options Collection run options
* @returns Test results
*/
async runCollection(options: CollectionRunOptions): Promise<TestResult> {
return new Promise((resolve, reject) => {
const startTime = new Date().toISOString();
newman.run({
collection: options.collection,
environment: options.environment,
globals: options.globals,
iterationCount: options.iterationCount,
reporters: 'cli'
}, (err, summary) => {
if (err) {
reject(err);
return;
}
const endTime = new Date().toISOString();
// Format the results
const result: TestResult = {
success: summary.run.failures.length === 0,
summary: {
total: summary.run.stats.tests.total || 0,
failed: summary.run.stats.tests.failed || 0,
passed: (summary.run.stats.tests.total || 0) - (summary.run.stats.tests.failed || 0)
},
failures: (summary.run.failures || [])
.map(extractFailureInfo)
.filter((failure): failure is TestFailure => failure !== null),
timings: {
started: startTime,
completed: endTime,
duration: new Date(endTime).getTime() - new Date(startTime).getTime()
}
};
resolve(result);
});
});
}
}
```
--------------------------------------------------------------------------------
/prompts/STEP_1_INITIAL_CODE_IMPLEMENTATION.md:
--------------------------------------------------------------------------------
```markdown
Detailed Implementation Plan for Postman MCP Server
1. Project Setup & Dependencies
Regular Dependencies
{
"dependencies": {
"@modelcontextprotocol/sdk": "^latest",
"newman": "^latest",
"zod": "^latest"
}
}
Dev Dependencies
{
"devDependencies": {
"typescript": "^latest",
"vitest": "^latest",
"@types/node": "^latest",
"@types/newman": "^latest",
"ts-node": "^latest",
"prettier": "^latest",
"eslint": "^latest",
"eslint-config-prettier": "^latest"
}
}
2. Project Structure
/postman-mcp-server
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── src/
│ ├── index.ts # Main entry point
│ ├── server/
│ │ ├── server.ts # MCP Server implementation
│ │ └── types.ts # Type definitions
│ ├── newman/
│ │ ├── runner.ts # Newman runner implementation
│ │ └── types.ts # Newman types
│ └── utils/
│ └── result-formatter.ts # Format Newman results
└── test/
├── server.test.ts # Server tests
├── newman-runner.test.ts # Newman runner tests
└── fixtures/ # Test fixtures
├── sample-collection.json
└── sample-environment.json
3. Key File Implementation Plans
src/index.ts
// Main entry point
// - Initialize MCP Server
// - Connect transport
// - Handle errors
src/server/types.ts
// Define interfaces for:
interface CollectionRunRequest {
collection: string;
environment?: string;
globals?: string;
iterationCount?: number;
}
interface TestResult {
success: boolean;
summary: TestSummary;
failures: TestFailure[];
timings: TestTimings;
}
src/server/server.ts
// Implement:
// 1. MCP Server setup
// 2. Tool registration
// 3. Request handling
// 4. Error handling
src/newman/runner.ts
// Implement:
// 1. Newman run configuration
// 2. Result collection
// 3. Error handling
// 4. Resource cleanup
src/utils/result-formatter.ts
// Implement:
// 1. Newman result parsing
// 2. MCP response formatting
// 3. Error formatting 4. Testing Strategy
Unit Tests (vitest.config.ts)
// Configure:
// - Test environment
// - Coverage reporting
// - Test matching patterns
Test Files
test/server.test.ts
// Test cases for:
// 1. Server initialization
// 2. Tool registration
// 3. Request handling
// 4. Error scenarios
test/newman-runner.test.ts
// Test cases for:
// 1. Collection running
// 2. Result parsing
// 3. Error handling
// 4. Resource cleanup 5. Configuration Files
tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"outDir": "./build",
"strict": true,
"esModuleInterop": true
}
} 6. Implementation Phases
Phase 1: Basic Setup
Project structure creation
Dependency installation
Configuration files
Phase 2: Core Implementation
Newman runner implementation
Result formatter
Basic error handling
Phase 3: MCP Server
Server setup
Tool registration
Request handling
Phase 4: Testing
Unit test implementation
Integration tests
Test fixtures
Phase 5: Documentation & Polish
API documentation
Usage examples
Error handling improvements 7. Testing Scenarios
Server Tests
Server initialization
Tool registration
Request validation
Error handling
Newman Runner Tests
Collection execution
Environment handling
Result parsing
Error scenarios
Integration Tests
```
--------------------------------------------------------------------------------
/test/fixtures/sample-collection.json:
--------------------------------------------------------------------------------
```json
{
"info": {
"name": "Sample API Tests",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Get User",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status code is 200', function () {",
" pm.response.to.have.status(200);",
"});",
"",
"pm.test('Response has user data', function () {",
" const responseJson = pm.response.json();",
" pm.expect(responseJson).to.have.property('id');",
" pm.expect(responseJson).to.have.property('name');",
"});"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://jsonplaceholder.typicode.com/users/1",
"protocol": "https",
"host": [
"jsonplaceholder",
"typicode",
"com"
],
"path": [
"users",
"1"
]
}
}
},
{
"name": "Create User",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status code is 201', function () {",
" pm.response.to.have.status(201);",
"});",
"",
"pm.test('Response has created user data', function () {",
" const responseJson = pm.response.json();",
" pm.expect(responseJson).to.have.property('id');",
" pm.expect(responseJson.name).to.eql('John Doe');",
"});"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"John Doe\",\n \"email\": \"[email protected]\"\n}"
},
"url": {
"raw": "https://jsonplaceholder.typicode.com/users",
"protocol": "https",
"host": [
"jsonplaceholder",
"typicode",
"com"
],
"path": [
"users"
]
}
}
}
]
}
```
--------------------------------------------------------------------------------
/example/postman/collection.json:
--------------------------------------------------------------------------------
```json
{
"info": {
"name": "Example API Tests",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "GET Items",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/items",
"host": ["{{baseUrl}}"],
"path": ["api", "items"]
}
},
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status code is 200', function () {",
" pm.response.to.have.status(200);",
"});",
"",
"pm.test('Response is an array', function () {",
" const responseData = pm.response.json();",
" pm.expect(Array.isArray(responseData)).to.be.true;",
"});",
"",
"pm.test('Response time is acceptable', function () {",
" pm.expect(pm.response.responseTime).to.be.below(1000);",
"});"
],
"type": "text/javascript"
}
}
]
},
{
"name": "Create Item",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Test Item\",\n \"description\": \"This is a test item\"\n}"
},
"url": {
"raw": "{{baseUrl}}/api/items",
"host": ["{{baseUrl}}"],
"path": ["api", "items"]
}
},
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status code is 201', function () {",
" pm.response.to.have.status(201);",
"});",
"",
"pm.test('Response has correct structure', function () {",
" const responseData = pm.response.json();",
" pm.expect(responseData).to.have.property('id');",
" pm.expect(responseData).to.have.property('name');",
" pm.expect(responseData).to.have.property('description');",
" pm.expect(responseData).to.have.property('createdAt');",
"});",
"",
"pm.test('Created item matches request', function () {",
" const responseData = pm.response.json();",
" const requestData = JSON.parse(pm.request.body.raw);",
" pm.expect(responseData.name).to.equal(requestData.name);",
" pm.expect(responseData.description).to.equal(requestData.description);",
"});"
],
"type": "text/javascript"
}
}
]
},
{
"name": "Get Current Bitcoin Price",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/currentprice",
"host": ["{{baseUrl}}"],
"path": ["api", "currentprice"]
}
},
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test(\"Status code is 200\", function () {",
" pm.response.to.have.status(200);",
"});"
],
"type": "text/javascript"
}
}
]
}
]
}
```
--------------------------------------------------------------------------------
/src/server/server.ts:
--------------------------------------------------------------------------------
```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
import { NewmanRunner } from "../newman/runner.js";
// Input validation schema
const RunCollectionSchema = z.object({
collection: z.string(),
environment: z.string().optional(),
globals: z.string().optional(),
iterationCount: z.number().min(1).optional()
});
export class PostmanServer {
private server: Server;
private runner: NewmanRunner;
constructor() {
this.server = new Server(
{
name: "postman-runner",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
this.runner = new NewmanRunner();
this.setupTools();
}
private setupTools(): void {
// Register available tools
this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: "run-collection",
description: "Run a Postman Collection using Newman",
inputSchema: {
type: "object",
properties: {
collection: {
type: "string",
description: "Path or URL to the Postman collection"
},
environment: {
type: "string",
description: "Optional path or URL to environment file"
},
globals: {
type: "string",
description: "Optional path or URL to globals file"
},
iterationCount: {
type: "number",
description: "Optional number of iterations to run"
}
},
required: ["collection"]
}
}
]
}));
// Handle tool execution
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name !== "run-collection") {
throw new Error(`Unknown tool: ${request.params.name}`);
}
// Validate input
const args = RunCollectionSchema.parse(request.params.arguments);
try {
// Run the collection
const result = await this.runner.runCollection(args);
// Format the response
return {
content: [{
type: "text",
text: JSON.stringify(result, null, 2)
}]
};
} catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
return {
content: [{
type: "text",
text: JSON.stringify({
error: errorMessage,
success: false
}, null, 2)
}],
isError: true
};
}
});
}
async start(): Promise<Server> {
// This will be connected in index.ts
return Promise.resolve(this.server);
}
}
```
--------------------------------------------------------------------------------
/test/newman-runner.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect, vi, beforeEach } from "vitest";
import { NewmanRunner } from "../src/newman/runner.js";
import type { NewmanRunSummary, NewmanRunOptions } from "newman";
import { EventEmitter } from "events";
const mockRun = vi.hoisted(() => vi.fn());
vi.mock("newman", () => ({
default: {
run: mockRun,
},
}));
describe("NewmanRunner", () => {
beforeEach(() => {
mockRun.mockReset();
mockRun.mockImplementation(
(
options: NewmanRunOptions,
callback: (err: Error | null, summary: NewmanRunSummary) => void,
) => {
callback(null, {} as NewmanRunSummary);
return new EventEmitter();
},
);
});
const runner = new NewmanRunner();
it("should successfully run a collection", async (): Promise<void> => {
// Mock successful newman run
const mockSummary = {
run: {
stats: {
tests: {
total: 5,
failed: 1,
},
},
failures: [
{
error: {
test: "Test case 1",
message: "Expected 200 but got 404",
},
source: {
request: {
method: "GET",
url: {
toString: () => "https://api.example.com/test",
},
},
},
},
],
},
};
mockRun.mockImplementationOnce(
(
options: NewmanRunOptions,
callback: (err: Error | null, summary: NewmanRunSummary) => void,
) => {
if (typeof callback === "function") {
callback(null, mockSummary as unknown as NewmanRunSummary);
}
return new EventEmitter();
},
);
const result = await runner.runCollection({
collection: "./test-collection.json",
});
expect(result.success).toBe(false);
expect(result.summary.total).toBe(5);
expect(result.summary.failed).toBe(1);
expect(result.summary.passed).toBe(4);
expect(result.failures).toHaveLength(1);
expect(result.failures[0]).toEqual({
name: "Test case 1",
error: "Expected 200 but got 404",
request: {
method: "GET",
url: "https://api.example.com/test",
},
});
});
it("should handle newman run errors", async (): Promise<void> => {
// Mock newman error
mockRun.mockImplementationOnce(
(
options: NewmanRunOptions,
callback: (err: Error | null, summary: NewmanRunSummary) => void,
) => {
if (typeof callback === "function") {
callback(
new Error("Failed to load collection"),
{} as NewmanRunSummary,
);
}
return new EventEmitter();
},
);
await expect(
runner.runCollection({
collection: "./invalid-collection.json",
}),
).rejects.toThrow("Failed to load collection");
});
it("should handle invalid failure objects", async (): Promise<void> => {
// Mock newman run with invalid failure object
const mockSummary = {
run: {
stats: {
tests: {
total: 1,
failed: 1,
},
},
failures: [
{
// Missing required properties
error: {},
source: {},
},
],
},
};
mockRun.mockImplementationOnce(
(
options: NewmanRunOptions,
callback: (err: Error | null, summary: NewmanRunSummary) => void,
) => {
if (typeof callback === "function") {
callback(null, mockSummary as unknown as NewmanRunSummary);
}
return new EventEmitter();
},
);
const result = await runner.runCollection({
collection: "./test-collection.json",
});
expect(result.success).toBe(false);
expect(result.failures).toHaveLength(0); // Invalid failure should be filtered out
});
});
```
--------------------------------------------------------------------------------
/example/prompts/CODING_STANDARDS.md:
--------------------------------------------------------------------------------
```markdown
# Express API Coding Standards
This document outlines the coding standards and best practices for building REST APIs with Express.js in this project. Following these standards ensures consistency, maintainability, and scalability of our APIs.
## Table of Contents
1. [Project Structure](#project-structure)
2. [API Design Principles](#api-design-principles)
3. [Error Handling](#error-handling)
4. [Security](#security)
5. [Performance](#performance)
6. [Documentation](#documentation)
7. [Testing](#testing)
## Project Structure
### Directory Layout
```
src/
├── index.ts # Application entry point
├── routes/ # Route definitions
│ ├── index.ts # Route aggregator
│ └── entity/ # Entity-specific routes
├── controllers/ # Request handlers
│ └── entity/ # Entity-specific controllers
├── services/ # Business logic
│ └── entity/ # Entity-specific services
├── models/ # Data models
│ └── entity/ # Entity-specific models
├── middleware/ # Custom middleware
├── utils/ # Utility functions
└── types/ # TypeScript type definitions
```
### Three-Layer Architecture
1. **Web Layer (Controllers & Routes)**
- Handles HTTP requests/responses
- Input validation
- Route definitions
- No business logic
2. **Service Layer**
- Contains business logic
- Orchestrates data access
- Independent of HTTP context
3. **Data Access Layer**
- Database interactions
- Data models
- Query operations
## API Design Principles
### URL Structure
- Use plural nouns for resources
- Use kebab-case for URLs
- Nest related resources
```typescript
// Good
GET /api/v1/users
GET /api/v1/users/:userId/orders
// Bad
GET /api/v1/getUser
GET /api/v1/user-get
```
### HTTP Methods
Use appropriate HTTP methods:
- GET: Retrieve resources
- POST: Create resources
- PUT: Update entire resources
- PATCH: Partial updates
- DELETE: Remove resources
### Request/Response Format
```typescript
// Success Response
{
"status": "success",
"data": {
// Response data
}
}
// Error Response
{
"status": "error",
"error": {
"code": "ERROR_CODE",
"message": "Human readable message"
}
}
```
### Versioning
- Include version in URL path
- Start with v1
```typescript
app.use("/api/v1/users", userRoutes);
```
## Error Handling
### HTTP Status Codes
Use appropriate status codes:
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
### Error Handler Implementation
```typescript
// Global error handler
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
const status = err.status || 500;
const message = err.message || "Internal server error";
res.status(status).json({
status: "error",
error: {
message,
...(process.env.NODE_ENV === "development" && { stack: err.stack }),
},
});
});
```
### Custom Error Classes
```typescript
class APIError extends Error {
constructor(
public status: number,
public message: string,
public code?: string
) {
super(message);
this.name = "APIError";
}
}
```
## Security
### Authentication & Authorization
- Use JWT for stateless authentication
- Implement role-based access control
- Store sensitive data in environment variables
### Middleware Security
```typescript
import helmet from "helmet";
import rateLimit from "express-rate-limit";
// Security headers
app.use(helmet());
// Rate limiting
const limiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 100, // limit each IP to 100 requests per windowMs
});
app.use(limiter);
```
### Input Validation
Use a validation library (e.g., express-validator):
```typescript
import { body, validationResult } from "express-validator";
const validateUser = [
body("email").isEmail(),
body("password").isLength({ min: 6 }),
(req: Request, res: Response, next: NextFunction) => {
const errors = validationResult(req);
if (!errors.isEmpty()) {
return res.status(400).json({ errors: errors.array() });
}
next();
},
];
```
## Performance
### Caching
Implement appropriate caching strategies:
```typescript
import apicache from "apicache";
// Cache successful GET requests for 15 minutes
app.use(apicache.middleware("15 minutes"));
```
### Database Optimization
- Use indexes appropriately
- Implement pagination
- Optimize queries
### Request Handling
```typescript
// Pagination example
router.get("/users", async (req: Request, res: Response) => {
const page = parseInt(req.query.page as string) || 1;
const limit = parseInt(req.query.limit as string) || 10;
const skip = (page - 1) * limit;
const users = await User.find().skip(skip).limit(limit);
res.json({
status: "success",
data: users,
pagination: {
page,
limit,
total: await User.countDocuments(),
},
});
});
```
## Documentation
### API Documentation
Use OpenAPI/Swagger for API documentation:
```typescript
/**
* @swagger
* /api/v1/users:
* get:
* summary: Retrieve users
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* description: Page number
* responses:
* 200:
* description: List of users
*/
```
### Code Documentation
- Use JSDoc for function documentation
- Document complex business logic
- Include examples for non-obvious implementations
## Testing
### Unit Tests
```typescript
describe("UserService", () => {
it("should create a new user", async () => {
const userData = {
email: "[email protected]",
password: "password123",
};
const user = await UserService.create(userData);
expect(user).toHaveProperty("id");
expect(user.email).toBe(userData.email);
});
});
```
### Integration Tests
```typescript
describe("User API", () => {
it("should return 401 for unauthorized access", async () => {
const response = await request(app)
.get("/api/v1/users")
.set("Accept", "application/json");
expect(response.status).toBe(401);
});
});
```
### API Testing
- Use Postman/Newman for API testing
- Maintain collection of API tests
- Include environment-specific configurations
## Additional Guidelines
1. **Dependency Management**
- Keep dependencies up to date
- Use exact versions in package.json
- Regularly audit dependencies for security
2. **Code Quality**
- Use ESLint for code linting
- Implement pre-commit hooks
- Follow TypeScript best practices
3. **Logging**
- Implement structured logging
- Use appropriate log levels
- Include request correlation IDs
4. **Configuration**
- Use environment variables for configuration
- Implement configuration validation
- Maintain separate configs for different environments
5. **Monitoring**
- Implement health checks
- Monitor API metrics
- Set up error tracking
## ERROR Handling Examples
When displaying error or status the following is a working example of an error case
res.status(500).json({ error: "Something went wrong!" });
```
app.use((err: Error, _req: Request, res: Response) => {
console.error(err.stack);
res.status(500).json({ error: "Something went wrong!" });
});
```
Here is another example of returning a 400 status with error code
```
// Validate request body
if (!name || !description) {
return res.status(400).json({ error: "Name and description are required" });
}
```
Here is success example
```
res.status(201).json(newItem);
```
IMPORTANT. ALWAYS USE
res.status(XXX).json() when responding
Never use
```
res.json({
status: "success",
data: response.data
});
```
As you are not setting a status
Remember: These standards are guidelines, not rigid rules. Use judgment to determine when to deviate based on specific requirements or constraints.
```
--------------------------------------------------------------------------------
/test/server.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect, vi, beforeEach } from "vitest";
// Define types for collection run parameters
interface CollectionRunParams {
collection: string;
environment?: string;
globals?: string;
iterationCount?: number;
}
vi.mock("../src/newman/runner.js", () => ({
NewmanRunner: vi.fn().mockImplementation(() => ({
runCollection: vi.fn(),
})),
}));
import { PostmanServer } from "../src/server/server.js";
import { NewmanRunner } from "../src/newman/runner.js";
const MockedNewmanRunner = vi.mocked(NewmanRunner);
describe("PostmanServer", () => {
let server: PostmanServer;
beforeEach(() => {
vi.clearAllMocks();
server = new PostmanServer();
});
it("should initialize server with proper configuration", async (): Promise<void> => {
const mcpServer = await server.start();
// Verify server is properly initialized with expected methods
expect(mcpServer).toBeDefined();
expect(typeof mcpServer.connect).toBe("function");
expect(typeof mcpServer.close).toBe("function");
});
it("should properly instantiate NewmanRunner", () => {
expect(MockedNewmanRunner).toHaveBeenCalledTimes(1);
// Verify NewmanRunner was constructed with no arguments
expect(MockedNewmanRunner).toHaveBeenCalledWith();
});
it("should register run-collection tool", async () => {
const mcpServer = await server.start();
// Verify server is properly initialized
expect(mcpServer).toBeDefined();
// Verify the server has the expected methods
expect(typeof mcpServer.setRequestHandler).toBe("function");
expect(typeof mcpServer.connect).toBe("function");
});
it("should execute collection run with minimal parameters", async () => {
// Setup mock response
const mockResult = {
success: true,
summary: { total: 1, failed: 0, passed: 1 },
};
// Setup mock runner with spy
const runCollectionSpy = vi.fn().mockResolvedValue(mockResult);
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running a collection
await mockRunner.runCollection({ collection: "./test-collection.json" });
// Verify mock runner was called with correct parameters
expect(runCollectionSpy).toHaveBeenCalledWith({
collection: "./test-collection.json",
});
// Verify mock runner returned expected result
expect(await runCollectionSpy.mock.results[0].value).toEqual(mockResult);
});
it("should execute collection run with all parameters", async () => {
// Setup mock response
const mockResult = {
success: true,
summary: {
total: 2,
failed: 0,
passed: 2,
},
};
// Setup mock runner with spy
const runCollectionSpy = vi.fn().mockResolvedValue(mockResult);
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running a collection with all parameters
await mockRunner.runCollection({
collection: "./test-collection.json",
environment: "./env.json",
globals: "./globals.json",
iterationCount: 2,
});
// Verify mock runner was called with all parameters
expect(runCollectionSpy).toHaveBeenCalledWith({
collection: "./test-collection.json",
environment: "./env.json",
globals: "./globals.json",
iterationCount: 2,
});
// Verify mock runner returned expected result
expect(await runCollectionSpy.mock.results[0].value).toEqual(mockResult);
});
it("should handle invalid collection path error", async () => {
// Setup mock runner with spy that rejects
const runCollectionSpy = vi
.fn()
.mockRejectedValue(new Error("Could not find collection file"));
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running with invalid collection path
await expect(
mockRunner.runCollection({
collection: "./invalid-collection.json",
}),
).rejects.toThrow("Could not find collection file");
});
it("should handle invalid environment file error", async () => {
// Setup mock runner with spy that rejects
const runCollectionSpy = vi
.fn()
.mockRejectedValue(new Error("Could not find environment file"));
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running with invalid environment file
await expect(
mockRunner.runCollection({
collection: "./test-collection.json",
environment: "./invalid-env.json",
}),
).rejects.toThrow("Could not find environment file");
});
it("should handle invalid globals file error", async () => {
// Setup mock runner with spy that rejects
const runCollectionSpy = vi
.fn()
.mockRejectedValue(new Error("Could not find globals file"));
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running with invalid globals file
await expect(
mockRunner.runCollection({
collection: "./test-collection.json",
globals: "./invalid-globals.json",
}),
).rejects.toThrow("Could not find globals file");
});
it("should handle invalid iterationCount error", async () => {
// Setup mock runner with spy that rejects
const runCollectionSpy = vi
.fn()
.mockRejectedValue(new Error("iterationCount must be greater than 0"));
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running with invalid iteration count
await expect(
mockRunner.runCollection({
collection: "./test-collection.json",
iterationCount: 0,
}),
).rejects.toThrow("iterationCount must be greater than 0");
});
it("should reject when collection parameter is missing", async () => {
// Setup mock runner with spy that rejects
const runCollectionSpy = vi
.fn()
.mockRejectedValue(new Error("collection parameter is required"));
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running without collection parameter
await expect(
mockRunner.runCollection({} as Partial<CollectionRunParams>),
).rejects.toThrow("collection parameter is required");
});
it("should reject when iterationCount is less than 1", async () => {
// Setup mock runner with spy that rejects
const runCollectionSpy = vi
.fn()
.mockRejectedValue(new Error("iterationCount must be greater than 0"));
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running with invalid iteration count
await expect(
mockRunner.runCollection({
collection: "./test-collection.json",
iterationCount: -1,
}),
).rejects.toThrow("iterationCount must be greater than 0");
});
it("should reject when unknown tool name is provided", async () => {
// Setup mock runner with spy that rejects
const runCollectionSpy = vi
.fn()
.mockRejectedValue(new Error("unknown tool parameter"));
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running with unknown tool name
await expect(
mockRunner.runCollection({
collection: "./test-collection.json",
tool: "unknown-tool",
} as CollectionRunParams & { tool: string }),
).rejects.toThrow("unknown tool parameter");
});
it("should handle invalid input types", async () => {
// Setup mock runner with spy that rejects
const runCollectionSpy = vi
.fn()
.mockRejectedValue(new Error("collection must be a string"));
const mockRunner = { runCollection: runCollectionSpy };
vi.mocked(NewmanRunner).mockImplementation(() => mockRunner);
// Simulate running with invalid input type
await expect(
mockRunner.runCollection({
collection: 123,
} as unknown as CollectionRunParams),
).rejects.toThrow("collection must be a string");
});
});
```
--------------------------------------------------------------------------------
/prompts/POSTMAN_NEWMAN_REFERENCE_DOCS.md:
--------------------------------------------------------------------------------
```markdown
The following is reference documentation on Postman and Newman
###
Newman is a command-line collection runner for Postman. It allows you to effortlessly run and test a Postman collection directly from the command-line. It is built with extensibility in mind so that you can easily integrate it with your continuous integration servers and build systems.
Table of contents
Getting Started
Usage
Using Newman CLI
Using Newman as a Library
Using Reporters with Newman
Command Line Options
newman-options
newman-run
SSL
Configuring Proxy
API Reference
newman run
Run summary object
Events emitted during a collection run
Reporters
Configuring Reporters
CLI Reporter
JSON Reporter
JUnit Reporter
HTML Reporter
External Reporters
Using External Reporters
Creating Your Own Reporter
File Uploads
Using Newman with the Postman API
Using Newman in Docker
Using Socks Proxy
Migration Guide
Compatibility
Contributing
Community Support
License
Getting started
To run Newman, ensure that you have Node.js >= v16. Install Node.js via package manager.
Installation
The easiest way to install Newman is using NPM. If you have Node.js installed, it is most likely that you have NPM installed as well.
$ npm install -g newman
This installs Newman globally on your system allowing you to run it from anywhere. If you want to install it locally, Just remove the -g flag.
Using Homebrew
Install Newman globally on your system using Homebrew.
$ brew install newman
back to top
Usage
Using Newman CLI
The newman run command allows you to specify a collection to be run. You can easily export your Postman Collection as a json file from the Postman App and run it using Newman.
$ newman run examples/sample-collection.json
If your collection file is available as an URL (such as from our Cloud API service), Newman can fetch your file and run it as well.
$ newman run https://www.getpostman.com/collections/631643-f695cab7-6878-eb55-7943-ad88e1ccfd65-JsLv
For the complete list of options, refer the Command Line Options section below.
terminal-demo
Using Newman as a Library
Newman can be easily used within your JavaScript projects as a Node.js module. The entire set of Newman CLI functionality is available for programmatic use as well. The following example runs a collection by reading a JSON collection file stored on disk.
const newman = require('newman'); // require newman in your project
// call newman.run to pass `options` object and wait for callback
newman.run({
collection: require('./sample-collection.json'),
reporters: 'cli'
}, function (err) {
if (err) { throw err; }
console.log('collection run complete!');
});
For the complete list of options, refer the API Reference section below.
Using Reporters with Newman
Reporters provide information about the current collection run in a format that is easy to both: disseminate and assimilate. Reporters can be configured using the -r or --reporters options. Inbuilt reporters in newman are: cli, json, junit, progress and emojitrain.
CLI reporter is enabled by default when Newman is used as a CLI, you do not need to specifically provide the same as part of reporters option. However, enabling one or more of the other reporters will result in no CLI output. Explicitly enable the CLI option in such a scenario. Check the example given below using the CLI and JSON reporters:
$ newman run examples/sample-collection.json -r cli,json
For more details on Reporters and writing your own External Reporters refer to their corresponding sections below.
back to top
Command Line Options
newman [options]
-h, --help
Show command line help, including a list of options, and sample use cases.
-v, --version
Displays the current Newman version, taken from package.json
newman run <collection-file-source> [options]
-e <source>, --environment <source>
Specify an environment file path or URL. Environments provide a set of variables that one can use within collections. Read More
-g <source>, --globals <source>
Specify the file path or URL for global variables. Global variables are similar to environment variables but have a lower precedence and can be overridden by environment variables having the same name.
-d <source>, --iteration-data <source>
Specify a data source file (JSON or CSV) to be used for iteration as a path to a file or as a URL. Read More
-n <number>, --iteration-count <number>
Specifies the number of times the collection has to be run when used in conjunction with iteration data file.
--folder <name>
Run requests within a particular folder/folders or specific requests in a collection. Multiple folders or requests can be specified by using --folder multiple times, like so: --folder f1 --folder f2 --folder r1 --folder r2.
--working-dir <path>
Set the path of the working directory to use while reading files with relative paths. Default to current directory.
--no-insecure-file-read
Prevents reading of files situated outside of the working directory.
--export-environment <path>
The path to the file where Newman will output the final environment variables file before completing a run.
--export-globals <path>
The path to the file where Newman will output the final global variables file before completing a run.
--export-collection <path>
The path to the file where Newman will output the final collection file before completing a run.
--timeout <ms>
Specify the time (in milliseconds) to wait for the entire collection run to complete execution.
--timeout-request <ms>
Specify the time (in milliseconds) to wait for requests to return a response.
--timeout-script <ms>
Specify the time (in milliseconds) to wait for scripts to complete execution.
-k, --insecure
Disables SSL verification checks and allows self-signed SSL certificates.
--ignore-redirects
Prevents newman from automatically following 3XX redirect responses.
--delay-request
Specify the extent of delay between requests (milliseconds).
--cookie-jar <path>
Specify the file path for a JSON Cookie Jar. Uses tough-cookie to deserialize the file.
--export-cookie-jar <path>
The path to the file where Newman will output the final cookie jar file before completing a run. Uses tough-cookie's serialize method.
--bail [optional modifiers]
Specify whether or not to stop a collection run on encountering the first test script error.
Can optionally accept modifiers, currently include folder and failure.
folder allows you to skip the entire collection run in case an invalid folder was specified using the --folder option or an error was encountered in general.
On the failure of a test, failure would gracefully stop a collection run after completing the current test script.
-x, --suppress-exit-code
Specify whether or not to override the default exit code for the current run.
--color <value>
Enable or Disable colored CLI output. The color value can be any of the three: on, off or auto(default).
With auto, Newman attempts to automatically turn color on or off based on the color support in the terminal. This behaviour can be modified by using the on or off value accordingly.
--disable-unicode
Specify whether or not to force the unicode disable option. When supplied, all symbols in the output will be replaced by their plain text equivalents.
--global-var "<global-variable-name>=<global-variable-value>"
Allows the specification of global variables via the command line, in a key=value format. Multiple CLI global variables can be added by using --global-var multiple times, like so: --global-var "foo=bar" --global-var "alpha=beta".
--env-var "<environment-variable-name>=<environment-variable-value>"
Allows the specification of environment variables via the command line, in a key=value format. Multiple CLI environment variables can be added by using --env-var multiple times, like so: --env-var "foo=bar" --env-var "alpha=beta".
--verbose
Show detailed information of collection run and each request sent.
SSL
Client Certificates
Client certificates are an alternative to traditional authentication mechanisms. These allow their users to make authenticated requests to a server, using a public certificate, and an optional private key that verifies certificate ownership. In some cases, the private key may also be protected by a secret passphrase, providing an additional layer of authentication security.
Newman supports SSL client certificates, via the following CLI options:
Using a single SSL client certificate
--ssl-client-cert
The path to the public client certificate file.
--ssl-client-key
The path to the private client key (optional).
--ssl-client-passphrase
The secret passphrase used to protect the private client key (optional).
Using SSL client certificates configuration file (supports multiple certificates per run)
--ssl-client-cert-list
The path to the SSL client certificate list configuration file (JSON format). See examples/ssl-client-cert-list.json.
This option allows setting different SSL client certificate according to URL or hostname. This option takes precedence over --ssl-client-cert, --ssl-client-key and --ssl-client-passphrase options. If there is no match for the URL in the list, these options are used as fallback.
Trusted CA
When it is not wanted to use the --insecure option, additionally trusted CA certificates can be provided like this:
--ssl-extra-ca-certs
The path to the file, that holds one or more trusted CA certificates in PEM format
Configuring Proxy
Newman can also be configured to work with proxy settings via the following environment variables:
HTTP_PROXY / http_proxy
HTTPS_PROXY / https_proxy
NO_PROXY / no_proxy
For more details on using these variables, refer here.
back to top
API Reference
newman.run(options: object , callback: function) => run: EventEmitter
The run function executes a collection and returns the run result to a callback function provided as parameter. The return of the newman.run function is a run instance, which emits run events that can be listened to.
Parameter Description
options This is a required argument and it contains all information pertaining to running a collection.
Required
Type: object
options.collection The collection is a required property of the options argument. It accepts an object representation of a Postman Collection which should resemble the schema mentioned at https://schema.getpostman.com/. The value of this property could also be an instance of Collection Object from the Postman Collection SDK.
As string, one can provide a URL where the Collection JSON can be found (e.g. Postman Cloud API service) or path to a local JSON file.
Required
Type: object|string PostmanCollection
options.environment One can optionally pass an environment file path or URL as string to this property and that will be used to read Postman Environment Variables from. This property also accepts environment variables as an object. Environment files exported from Postman App can be directly used here.
Optional
Type: object|string
options.envVar One can optionally pass environment variables as an array of key-value string object pairs. It will be used to read Postman Environment Variables as well as overwrite environment variables from options.environments.
Optional
Type: array|object
options.globals Postman Global Variables can be optionally passed on to a collection run in form of path to a file or URL. It also accepts variables as an object.
Optional
Type: object|string
options.globalVar One can optionally pass global environment variables as an array of key-value string object pairs. It will be used to read Postman Global Environment Variables as well as overwrite global environment variables from options.globals.
Optional
Type: array|object
options.iterationCount Specify the number of iterations to run on the collection. This is usually accompanied by providing a data file reference as options.iterationData.
Optional
Type: number, Default value: 1
options.iterationData Path to the JSON or CSV file or URL to be used as data source when running multiple iterations on a collection.
Optional
Type: string
options.folder The name or ID of the folder/folders (ItemGroup) in the collection which would be run instead of the entire collection.
Optional
Type: string|array
options.workingDir The path of the directory to be used as working directory.
Optional
Type: string, Default value: Current Directory
options.insecureFileRead Allow reading files outside of working directory.
Optional
Type: boolean, Default value: true
options.timeout Specify the time (in milliseconds) to wait for the entire collection run to complete execution.
Optional
Type: number, Default value: Infinity
options.timeoutRequest Specify the time (in milliseconds) to wait for requests to return a response.
Optional
Type: number, Default value: Infinity
options.timeoutScript Specify the time (in milliseconds) to wait for scripts to return a response.
Optional
Type: number, Default value: Infinity
options.delayRequest Specify the time (in milliseconds) to wait for between subsequent requests.
Optional
Type: number, Default value: 0
options.ignoreRedirects This specifies whether newman would automatically follow 3xx responses from servers.
Optional
Type: boolean, Default value: false
options.insecure Disables SSL verification checks and allows self-signed SSL certificates.
Optional
Type: boolean, Default value: false
options.bail A switch to specify whether or not to gracefully stop a collection run (after completing the current test script) on encountering the first error. Takes additional modifiers as arguments to specify whether to end the run with an error for invalid name or path.
Available modifiers: folder and failure.
eg. bail : ['folder']
Optional
Type: boolean|object, Default value: false
options.suppressExitCode If present, allows overriding the default exit code from the current collection run, useful for bypassing collection result failures. Takes no arguments.
Optional
Type: boolean, Default value: false
options.reporters Specify one reporter name as string or provide more than one reporter name as an array.
Available reporters: cli, json, junit, progress and emojitrain.
Optional
Type: string|array
options.reporter Specify options for the reporter(s) declared in options.reporters.
e.g. reporter : { junit : { export : './xmlResults.xml' } }
e.g. reporter : { html : { export : './htmlResults.html', template: './customTemplate.hbs' } }
Optional
Type: object
options.color Enable or Disable colored CLI output.
Available options: on, off and auto
Optional
Type: string, Default value: auto
options.sslClientCert The path to the public client certificate file.
Optional
Type: string
options.sslClientKey The path to the private client key file.
Optional
Type: string
options.sslClientPassphrase The secret client key passphrase.
Optional
Type: string
options.sslClientCertList The path to the client certificate configuration list file. This option takes precedence over sslClientCert, sslClientKey and sslClientPassphrase. When there is no match in this configuration list, sslClientCert is used as fallback.
Optional
Type: string|array
options.sslExtraCaCerts The path to the file, that holds one or more trusted CA certificates in PEM format.
Optional
Type: string
options.requestAgents Specify the custom requesting agents to be used when performing HTTP and HTTPS requests respectively. Example: Using Socks Proxy
Optional
Type: object
options.cookieJar One can optionally pass a CookieJar file path as string to this property and that will be deserialized using tough-cookie. This property also accepts a tough-cookie CookieJar instance.
Optional
Type: object|string
options.newmanVersion The Newman version used for the collection run.
This will be set by Newman
callback Upon completion of the run, this callback is executed with the error, summary argument.
Required
Type: function
newman.run~callback(error: object , summary: object)
The callback parameter of the newman.run function receives two arguments: (1) error and (2) summary
Argument Description
error In case newman faces an error during the run, the error is passed on to this argument of callback. By default, only fatal errors, such as the ones caused by any fault inside Newman is passed on to this argument. However, setting abortOnError:true or abortOnFailure:true as part of run options will cause newman to treat collection script syntax errors and test failures as fatal errors and be passed down here while stopping the run abruptly at that point.
Type: object
summary The run summary will contain information pertaining to the run.
Type: object
summary.error An error object which if exists, contains an error message describing the message
Type: object
summary.collection This object contains information about the collection being run, it's requests, and their associated pre-request scripts and tests.
Type: object
summary.environment An object with environment variables used for the current run, and the usage status for each of those variables.
Type: object
summary.globals This object holds details about the globals used within the collection run namespace.
Type: object
summary.run A cumulative run summary object that provides information on .
Type: object
summary.run.stats An object which provides details about the total, failed, and pending counts for pre request scripts, tests, assertions, requests, and more.
Type: object
summary.run.failures An array of failure objects, with each element holding details, including the assertion that failed, and the request.
Type: array.<object>
summary.run.executions This object contains information about each request, along with it's associated activities within the scope of the current collection run.
Type: array.<object>
newman.run~events
Newman triggers a whole bunch of events during the run.
newman.run({
collection: require('./sample-collection.json'),
iterationData: [{ "var": "data", "var_beta": "other_val" }],
globals: {
"id": "5bfde907-2a1e-8c5a-2246-4aff74b74236",
"name": "test-env",
"values": [
{
"key": "alpha",
"value": "beta",
"type": "text",
"enabled": true
}
],
"timestamp": 1404119927461,
"\_postman_variable_scope": "globals",
"\_postman_exported_at": "2016-10-17T14:31:26.200Z",
"\_postman_exported_using": "Postman/4.8.0"
},
globalVar: [
{ "key":"glboalSecret", "value":"globalSecretValue" },
{ "key":"globalAnotherSecret", "value":`${process.env.GLOBAL_ANOTHER_SECRET}`}
],
environment: {
"id": "4454509f-00c3-fd32-d56c-ac1537f31415",
"name": "test-env",
"values": [
{
"key": "foo",
"value": "bar",
"type": "text",
"enabled": true
}
],
"timestamp": 1404119927461,
"\_postman_variable_scope": "environment",
"\_postman_exported_at": "2016-10-17T14:26:34.940Z",
"\_postman_exported_using": "Postman/4.8.0"
},
envVar: [
{ "key":"secret", "value":"secretValue" },
{ "key":"anotherSecret", "value":`${process.env.ANOTHER_SECRET}`}
],
}).on('start', function (err, args) { // on start of run, log to console
console.log('running a collection...');
}).on('done', function (err, summary) {
if (err || summary.error) {
console.error('collection run encountered an error.');
}
else {
console.log('collection run completed.');
}
});
All events receive two arguments (1) error and (2) args. The list below describes the properties of the second argument object. Learn more
Event Description
start The start of a collection run
beforeIteration Before an iteration commences
beforeItem Before an item execution begins (the set of prerequest->request->test)
beforePrerequest Before prerequest script is execution starts
prerequest After prerequest script execution completes
beforeRequest Before an HTTP request is sent
request After response of the request is received
beforeTest Before test script is execution starts
test After test script execution completes
beforeScript Before any script (of type test or prerequest) is executed
script After any script (of type test or prerequest) is executed
item When an item (the whole set of prerequest->request->test) completes
iteration After an iteration completes
assertion This event is triggered for every test assertion done within test scripts
console Every time a console function is called from within any script, this event is propagated
exception When any asynchronous error happen in scripts this event is triggered
beforeDone An event that is triggered prior to the completion of the run
done This event is emitted when a collection run has completed, with or without errors
back to top
Reporters
Configuring Reporters
-r <reporter-name>, --reporters <reporter-name>
Specify one reporter name as string or provide more than one reporter name as a comma separated list of reporter names. Available reporters are: cli, json, junit, progress and emojitrain.
Spaces should not be used between reporter names / commas whilst specifying a comma separated list of reporters. For instance:
✅ -r cli,json,junit
❌ -r cli , json,junit
--reporter-{{reporter-name}}-{{reporter-option}}
When multiple reporters are provided, if one needs to specifically override or provide an option to one reporter, this is achieved by prefixing the option with --reporter-{{reporter-name}}-.
For example, ... --reporters cli,json --reporter-cli-silent would silence the CLI reporter only.
--reporter-{{reporter-options}}
If more than one reporter accepts the same option name, they can be provided using the common reporter option syntax.
For example, ... --reporters cli,json --reporter-silent passes the silent: true option to both JSON and CLI reporter.
Note: Sample collection reports have been provided in examples/reports.
CLI Reporter
The built-in CLI reporter supports the following options, use them with appropriate argument switch prefix. For example, the option no-summary can be passed as --reporter-no-summary or --reporter-cli-no-summary.
CLI reporter is enabled by default when Newman is used as a CLI, you do not need to specifically provide the same as part of --reporters option. However, enabling one or more of the other reporters will result in no CLI output. Explicitly enable the CLI option in such a scenario.
CLI Option Description
--reporter-cli-silent The CLI reporter is internally disabled and you see no output to terminal.
| --reporter-cli-show-timestamps | This prints the local time for each request made. | | --reporter-cli-no-summary | The statistical summary table is not shown. | | --reporter-cli-no-failures | This prevents the run failures from being separately printed. | | --reporter-cli-no-assertions | This turns off the output for request-wise assertions as they happen. | | --reporter-cli-no-success-assertions | This turns off the output for successful assertions as they happen. | | --reporter-cli-no-console | This turns off the output of console.log (and other console calls) from collection's scripts. | | --reporter-cli-no-banner | This turns off the newman banner shown at the beginning of each collection run. |
JSON Reporter
The built-in JSON reporter is useful in producing a comprehensive output of the run summary. It takes the path to the file where to write the report. The content of this file is exactly the same as the summary parameter sent to the callback when Newman is used as a library.
To enable JSON reporter, provide --reporters json as a CLI option.
CLI Option Description
--reporter-json-export <path> Specify a path where the output JSON file will be written to disk. If not specified, the file will be written to newman/ in the current working directory. If the specified path does not exist, it will be created. However, if the specified path is a pre-existing directory, the report will be generated in that directory.
JUNIT/XML Reporter
The built-in JUnit reporter can output a summary of the collection run to a JUnit compatible XML file. To enable the JUNIT reporter, provide --reporters junit as a CLI option.
CLI Option Description
--reporter-junit-export <path> Specify a path where the output XML file will be written to disk. If not specified, the file will be written to newman/ in the current working directory. If the specified path does not exist, it will be created. However, if the specified path is a pre-existing directory, the report will be generated in that directory.
HTML Reporter
An external reporter, maintained by Postman, which can be installed via npm install -g newman-reporter-html. This reporter was part of the Newman project but was separated out into its own project in V4.
The complete installation and usage guide is available at newman-reporter-html. Once the HTML reporter is installed you can provide --reporters html as a CLI option.
back to top
External Reporters
Using External Reporters
Newman also supports external reporters, provided that the reporter works with Newman's event sequence. Working examples of how Newman reporters work can be found in lib/reporters.
For instance, to use the Newman HTML Reporter:
Install the reporter package. Note that the name of the package is of the form newman-reporter-<name>. The installation should be global if Newman is installed globally, local otherwise. (Remove -g flag from the command below for a local installation.)
$ npm install -g newman-reporter-html
Use the installed reporter, either via the CLI, or programmatic usage. Here, the newman-reporter prefix is not required while specifying the reporter name in the options.
$ newman run /path/to/collection.json -r cli,html
const newman = require('newman');
newman.run({
collection: '/path/to/collection.json',
reporters: ['cli', 'html']
}, process.exit);
Community Maintained Reporters
Several members of the Postman community have created custom reporters offering different option to output the data coming from Newman. Listed below is a selection of these but more can be found here on NPM.
Once the custom reporter NPM package has been installed either globally or locally, this can be then used with Newman in the following ways:
$ newman run /path/to/collection.json -r htmlextra,csv
const newman = require('newman');
newman.run({
collection: '/path/to/collection.json',
reporters: ['htmlextra', 'csv']
}, process.exit);
allure - This reporter allow to create fully-featured allure reports that can allow you to have easy to understand HTML reports with features like historical data, link tests to the JIRA and all other benefits of using allure framework.
htmlextra - This is an updated version of the standard HTML reporter containing a more in-depth data output and a few helpful extras
csv - This reporter creates a csv file containing the high level summary of the Collection run
json-summary - A Newman JSON Reporter that strips the results down to a minimum
teamcity - A reporter built to be used with the Team City CI server
testrail - A reporter built for Test Rail, the test case management tool
statsd - This reporter can be used to send the Collection run data to statsd and used on time series analytic tools like Grafana
confluence - Confluence reporter for Newman that uploads a Newman report on a Confluence page
influxdb - This reporter sends the test results information to InfluxDB which can be used from Grafana to build dashboards
Creating Your Own Reporter
A custom reporter is a Node module with a name of the form newman-reporter-<name>. To create a custom reporter:
Navigate to a directory of your choice, and create a blank npm package with npm init.
Add an index.js file, that exports a function of the following form:
function CustomNewmanReporter (emitter, reporterOptions, collectionRunOptions) {
// emitter is an event emitter that triggers the following events: https://github.com/postmanlabs/newman#newmanrunevents
// reporterOptions is an object of the reporter specific options. See usage examples below for more details.
// collectionRunOptions is an object of all the collection run options: https://github.com/postmanlabs/newman#newmanrunoptions-object--callback-function--run-eventemitter
}
module.exports = CustomNewmanReporter
To use your reporter locally, use the npm pack command to create a .tgz file. Once created, this can be installed using the npm i -g newman-reporter-<name>.<version>.tgz command.
Once you're happy with your reporter, it can be published to npm using npm publish. This will then be made available for other people to download.
Scoped reporter package names like @myorg/newman-reporter-<name> are also supported. Working reporter examples can be found in lib/reporters.
back to top
File uploads
Newman also supports file uploads for request form data. The files must be present in the current working directory. Your collection must also contain the filename in the "src" attribute of the request.
In this collection, sample-file.txt should be present in the current working directory.
{
"info": {
"name": "file-upload"
},
"item": [
{
"request": {
"url": "https://postman-echo.com/post",
"method": "POST",
"body": {
"mode": "formdata",
"formdata": [
{
"key": "file",
"type": "file",
"enabled": true,
"src": "sample-file.txt"
}
]
}
}
}
]
}
$ ls
file-upload.postman_collection.json sample-file.txt
$ newman run file-upload.postman_collection.json
back to top
Using Newman with the Postman API
1 Generate an API key
2 Fetch a list of your collections from: https://api.getpostman.com/collections?apikey=$apiKey
3 Get the collection link via it's uid: https://api.getpostman.com/collections/$uid?apikey=$apiKey
4 Obtain the environment URI from: https://api.getpostman.com/environments?apikey=$apiKey
5 Using the collection and environment URIs acquired in steps 3 and 4, run the collection as follows:
$ newman run "https://api.getpostman.com/collections/$uid?apikey=$apiKey" \
--environment "https://api.getpostman.com/environments/$uid?apikey=$apiKey"
back to top
Using Newman in Docker
To use Newman in Docker check our docker documentation.
Using Socks Proxy
When using Newman as a library, you can pass a custom HTTP(S) agent which will be used for making the requests. Here's an example of how to setup socks proxy using a custom agent.
const newman = require('newman');
const SocksProxyAgent = require('socks-proxy-agent');
const requestAgent = new SocksProxyAgent({ host: 'localhost', port: '1080' });
newman.run({
collection: require('./sample-collection.json'),
requestAgents: {
http: requestAgent, // agent used for HTTP requests
https: requestAgent, // agent used for HTTPS requests
}
}, function (err) {
if (err) { throw err; }
console.log('collection run complete!');
});
back to top
Migration Guide
Newman v5 to v6 Migration Guide
Newman v5.x Documentation
Compatibility
NodeJS
Newman Node
v3.x >= v4.x
v4.x >= v6.x
v5.x >= v10.x
v6.x >= v16.x
The current Node version compatibility can also be seen from the engines.node property in package.json
File Encoding
Newman attempts to detect file encoding for files that are provided as command line input. However, it mostly relies on NodeJS and the underlying operating system to do the heavy lifting. Currently, ASCII, UTF-8, UTF-16LE and ISO-8859-1 are the only ones that are detection assisted.
###
```
--------------------------------------------------------------------------------
/prompts/MCP_REFERENCE_DOCS.md:
--------------------------------------------------------------------------------
```markdown
The following is information on building MCP Server Applications
The following is from the documents from the MCP Site
###
Get Started
Introduction
Get started with the Model Context Protocol (MCP)
MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
Why MCP?
MCP helps you build agents and complex workflows on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides:
A growing list of pre-built integrations that your LLM can directly plug into
The flexibility to switch between LLM providers and vendors
Best practices for securing your data within your infrastructure
General architecture
At its core, MCP follows a client-server architecture where a host application can connect to multiple servers:
Internet
Your Computer
MCP Protocol
MCP Protocol
MCP Protocol
Web APIs
Host with MCP Client
(Claude, IDEs, Tools)
MCP Server A
MCP Server B
MCP Server C
Local
Data Source A
Local
Data Source B
Remote
Service C
MCP Hosts: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP
MCP Clients: Protocol clients that maintain 1:1 connections with servers
MCP Servers: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol
Local Data Sources: Your computer’s files, databases, and services that MCP servers can securely access
Remote Services: External systems available over the internet (e.g., through APIs) that MCP servers can connect to
###
Here is information on MCP Core Architecture
###
Core architecture
Understand how MCP connects clients, servers, and LLMs
The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and integrations. This document covers the core architectural components and concepts.
Overview
MCP follows a client-server architecture where:
Hosts are LLM applications (like Claude Desktop or IDEs) that initiate connections
Clients maintain 1:1 connections with servers, inside the host application
Servers provide context, tools, and prompts to clients
Server Process
Server Process
Host (e.g., Claude Desktop)
Transport Layer
Transport Layer
MCP Client
MCP Client
MCP Server
MCP Server
Core components
Protocol layer
The protocol layer handles message framing, request/response linking, and high-level communication patterns.
TypeScript
Python
class Protocol<Request, Notification, Result> {
// Handle incoming requests
setRequestHandler<T>(schema: T, handler: (request: T, extra: RequestHandlerExtra) => Promise<Result>): void
// Handle incoming notifications
setNotificationHandler<T>(schema: T, handler: (notification: T) => Promise<void>): void
// Send requests and await responses
request<T>(request: Request, schema: T, options?: RequestOptions): Promise<T>
// Send one-way notifications
notification(notification: Notification): Promise<void>
}
Key classes include:
Protocol
Client
Server
Transport layer
The transport layer handles the actual communication between clients and servers. MCP supports multiple transport mechanisms:
Stdio transport
Uses standard input/output for communication
Ideal for local processes
HTTP with SSE transport
Uses Server-Sent Events for server-to-client messages
HTTP POST for client-to-server messages
All transports use JSON-RPC 2.0 to exchange messages. See the specification for detailed information about the Model Context Protocol message format.
Message types
MCP has these main types of messages:
Requests expect a response from the other side:
interface Request {
method: string;
params?: { ... };
}
Results are successful responses to requests:
interface Result {
[key: string]: unknown;
}
Errors indicate that a request failed:
interface Error {
code: number;
message: string;
data?: unknown;
}
Notifications are one-way messages that don’t expect a response:
interface Notification {
method: string;
params?: { ... };
}
Connection lifecycle
1. Initialization
Server
Client
Server
Client
Connection ready for use
initialize request
initialize response
initialized notification
Client sends initialize request with protocol version and capabilities
Server responds with its protocol version and capabilities
Client sends initialized notification as acknowledgment
Normal message exchange begins
2. Message exchange
After initialization, the following patterns are supported:
Request-Response: Client or server sends requests, the other responds
Notifications: Either party sends one-way messages
3. Termination
Either party can terminate the connection:
Clean shutdown via close()
Transport disconnection
Error conditions
Error handling
MCP defines these standard error codes:
enum ErrorCode {
// Standard JSON-RPC error codes
ParseError = -32700,
InvalidRequest = -32600,
MethodNotFound = -32601,
InvalidParams = -32602,
InternalError = -32603
}
SDKs and applications can define their own error codes above -32000.
Errors are propagated through:
Error responses to requests
Error events on transports
Protocol-level error handlers
Implementation example
Here’s a basic example of implementing an MCP server:
TypeScript
Python
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {
resources: {}
}
});
// Handle requests
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "example://resource",
name: "Example Resource"
}
]
};
});
// Connect transport
const transport = new StdioServerTransport();
await server.connect(transport);
Best practices
Transport selection
Local communication
Use stdio transport for local processes
Efficient for same-machine communication
Simple process management
Remote communication
Use SSE for scenarios requiring HTTP compatibility
Consider security implications including authentication and authorization
Message handling
Request processing
Validate inputs thoroughly
Use type-safe schemas
Handle errors gracefully
Implement timeouts
Progress reporting
Use progress tokens for long operations
Report progress incrementally
Include total progress when known
Error management
Use appropriate error codes
Include helpful error messages
Clean up resources on errors
Security considerations
Transport security
Use TLS for remote connections
Validate connection origins
Implement authentication when needed
Message validation
Validate all incoming messages
Sanitize inputs
Check message size limits
Verify JSON-RPC format
Resource protection
Implement access controls
Validate resource paths
Monitor resource usage
Rate limit requests
Error handling
Don’t leak sensitive information
Log security-relevant errors
Implement proper cleanup
Handle DoS scenarios
Debugging and monitoring
Logging
Log protocol events
Track message flow
Monitor performance
Record errors
Diagnostics
Implement health checks
Monitor connection state
Track resource usage
Profile performance
Testing
Test different transports
Verify error handling
Check edge cases
Load test servers
###
Here is documentation onf MCP Resources
###
Resources
Expose data and content from your servers to LLMs
Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions.
Resources are designed to be application-controlled, meaning that the client application can decide how and when they should be used. Different MCP clients may handle resources differently. For example:
Claude Desktop currently requires users to explicitly select resources before they can be used
Other clients might automatically select resources based on heuristics
Some implementations may even allow the AI model itself to determine which resources to use
Server authors should be prepared to handle any of these interaction patterns when implementing resource support. In order to expose data to models automatically, server authors should use a model-controlled primitive such as Tools.
Overview
Resources represent any kind of data that an MCP server wants to make available to clients. This can include:
File contents
Database records
API responses
Live system data
Screenshots and images
Log files
And more
Each resource is identified by a unique URI and can contain either text or binary data.
Resource URIs
Resources are identified using URIs that follow this format:
[protocol]://[host]/[path]
For example:
file:///home/user/documents/report.pdf
postgres://database/customers/schema
screen://localhost/display1
The protocol and path structure is defined by the MCP server implementation. Servers can define their own custom URI schemes.
Resource types
Resources can contain two types of content:
Text resources
Text resources contain UTF-8 encoded text data. These are suitable for:
Source code
Configuration files
Log files
JSON/XML data
Plain text
Binary resources
Binary resources contain raw binary data encoded in base64. These are suitable for:
Images
PDFs
Audio files
Video files
Other non-text formats
Resource discovery
Clients can discover available resources through two main methods:
Direct resources
Servers expose a list of concrete resources via the resources/list endpoint. Each resource includes:
{
uri: string; // Unique identifier for the resource
name: string; // Human-readable name
description?: string; // Optional description
mimeType?: string; // Optional MIME type
}
Resource templates
For dynamic resources, servers can expose URI templates that clients can use to construct valid resource URIs:
{
uriTemplate: string; // URI template following RFC 6570
name: string; // Human-readable name for this type
description?: string; // Optional description
mimeType?: string; // Optional MIME type for all matching resources
}
Reading resources
To read a resource, clients make a resources/read request with the resource URI.
The server responds with a list of resource contents:
{
contents: [
{
uri: string; // The URI of the resource
mimeType?: string; // Optional MIME type
// One of:
text?: string; // For text resources
blob?: string; // For binary resources (base64 encoded)
}
]
}
Servers may return multiple resources in response to one resources/read request. This could be used, for example, to return a list of files inside a directory when the directory is read.
Resource updates
MCP supports real-time updates for resources through two mechanisms:
List changes
Servers can notify clients when their list of available resources changes via the notifications/resources/list_changed notification.
Content changes
Clients can subscribe to updates for specific resources:
Client sends resources/subscribe with resource URI
Server sends notifications/resources/updated when the resource changes
Client can fetch latest content with resources/read
Client can unsubscribe with resources/unsubscribe
Example implementation
Here’s a simple example of implementing resource support in an MCP server:
TypeScript
Python
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {
resources: {}
}
});
// List available resources
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "file:///logs/app.log",
name: "Application Logs",
mimeType: "text/plain"
}
]
};
});
// Read resource contents
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const uri = request.params.uri;
if (uri === "file:///logs/app.log") {
const logContents = await readLogFile();
return {
contents: [
{
uri,
mimeType: "text/plain",
text: logContents
}
]
};
}
throw new Error("Resource not found");
});
Best practices
When implementing resource support:
Use clear, descriptive resource names and URIs
Include helpful descriptions to guide LLM understanding
Set appropriate MIME types when known
Implement resource templates for dynamic content
Use subscriptions for frequently changing resources
Handle errors gracefully with clear error messages
Consider pagination for large resource lists
Cache resource contents when appropriate
Validate URIs before processing
Document your custom URI schemes
Security considerations
When exposing resources:
Validate all resource URIs
Implement appropriate access controls
Sanitize file paths to prevent directory traversal
Be cautious with binary data handling
Consider rate limiting for resource reads
Audit resource access
Encrypt sensitive data in transit
Validate MIME types
Implement timeouts for long-running reads
Handle resource cleanup appropriately
Was this page helpful?
###
Here is information on MCP Tools
###
Concepts
Tools
Enable LLMs to perform actions through your server
Tools are a powerful primitive in the Model Context Protocol (MCP) that enable servers to expose executable functionality to clients. Through tools, LLMs can interact with external systems, perform computations, and take actions in the real world.
Tools are designed to be model-controlled, meaning that tools are exposed from servers to clients with the intention of the AI model being able to automatically invoke them (with a human in the loop to grant approval).
Overview
Tools in MCP allow servers to expose executable functions that can be invoked by clients and used by LLMs to perform actions. Key aspects of tools include:
Discovery: Clients can list available tools through the tools/list endpoint
Invocation: Tools are called using the tools/call endpoint, where servers perform the requested operation and return results
Flexibility: Tools can range from simple calculations to complex API interactions
Like resources, tools are identified by unique names and can include descriptions to guide their usage. However, unlike resources, tools represent dynamic operations that can modify state or interact with external systems.
Tool definition structure
Each tool is defined with the following structure:
{
name: string; // Unique identifier for the tool
description?: string; // Human-readable description
inputSchema: { // JSON Schema for the tool's parameters
type: "object",
properties: { ... } // Tool-specific parameters
}
}
Implementing tools
Here’s an example of implementing a basic tool in an MCP server:
TypeScript
Python
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {
tools: {}
}
});
// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [{
name: "calculate_sum",
description: "Add two numbers together",
inputSchema: {
type: "object",
properties: {
a: { type: "number" },
b: { type: "number" }
},
required: ["a", "b"]
}
}]
};
});
// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "calculate_sum") {
const { a, b } = request.params.arguments;
return {
content: [
{
type: "text",
text: String(a + b)
}
]
};
}
throw new Error("Tool not found");
});
Example tool patterns
Here are some examples of types of tools that a server could provide:
System operations
Tools that interact with the local system:
{
name: "execute_command",
description: "Run a shell command",
inputSchema: {
type: "object",
properties: {
command: { type: "string" },
args: { type: "array", items: { type: "string" } }
}
}
}
API integrations
Tools that wrap external APIs:
{
name: "github_create_issue",
description: "Create a GitHub issue",
inputSchema: {
type: "object",
properties: {
title: { type: "string" },
body: { type: "string" },
labels: { type: "array", items: { type: "string" } }
}
}
}
Data processing
Tools that transform or analyze data:
{
name: "analyze_csv",
description: "Analyze a CSV file",
inputSchema: {
type: "object",
properties: {
filepath: { type: "string" },
operations: {
type: "array",
items: {
enum: ["sum", "average", "count"]
}
}
}
}
}
Best practices
When implementing tools:
Provide clear, descriptive names and descriptions
Use detailed JSON Schema definitions for parameters
Include examples in tool descriptions to demonstrate how the model should use them
Implement proper error handling and validation
Use progress reporting for long operations
Keep tool operations focused and atomic
Document expected return value structures
Implement proper timeouts
Consider rate limiting for resource-intensive operations
Log tool usage for debugging and monitoring
Security considerations
When exposing tools:
Input validation
Validate all parameters against the schema
Sanitize file paths and system commands
Validate URLs and external identifiers
Check parameter sizes and ranges
Prevent command injection
Access control
Implement authentication where needed
Use appropriate authorization checks
Audit tool usage
Rate limit requests
Monitor for abuse
Error handling
Don’t expose internal errors to clients
Log security-relevant errors
Handle timeouts appropriately
Clean up resources after errors
Validate return values
Tool discovery and updates
MCP supports dynamic tool discovery:
Clients can list available tools at any time
Servers can notify clients when tools change using notifications/tools/list_changed
Tools can be added or removed during runtime
Tool definitions can be updated (though this should be done carefully)
Error handling
Tool errors should be reported within the result object, not as MCP protocol-level errors. This allows the LLM to see and potentially handle the error. When a tool encounters an error:
Set isError to true in the result
Include error details in the content array
Here’s an example of proper error handling for tools:
TypeScript
Python
try {
// Tool operation
const result = performOperation();
return {
content: [
{
type: "text",
text: `Operation successful: ${result}`
}
]
};
} catch (error) {
return {
isError: true,
content: [
{
type: "text",
text: `Error: ${error.message}`
}
]
};
}
This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.
Testing tools
A comprehensive testing strategy for MCP tools should cover:
Functional testing: Verify tools execute correctly with valid inputs and handle invalid inputs appropriately
Integration testing: Test tool interaction with external systems using both real and mocked dependencies
Security testing: Validate authentication, authorization, input sanitization, and rate limiting
Performance testing: Check behavior under load, timeout handling, and resource cleanup
Error handling: Ensure tools properly report errors through the MCP protocol and clean up resources
###
Here is information on MCP Prompts
###
Concepts
Prompts
Create reusable prompt templates and workflows
Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions.
Prompts are designed to be user-controlled, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use.
Overview
Prompts in MCP are predefined templates that can:
Accept dynamic arguments
Include context from resources
Chain multiple interactions
Guide specific workflows
Surface as UI elements (like slash commands)
Prompt structure
Each prompt is defined with:
{
name: string; // Unique identifier for the prompt
description?: string; // Human-readable description
arguments?: [ // Optional list of arguments
{
name: string; // Argument identifier
description?: string; // Argument description
required?: boolean; // Whether argument is required
}
]
}
Discovering prompts
Clients can discover available prompts through the prompts/list endpoint:
// Request
{
method: "prompts/list"
}
// Response
{
prompts: [
{
name: "analyze-code",
description: "Analyze code for potential improvements",
arguments: [
{
name: "language",
description: "Programming language",
required: true
}
]
}
]
}
Using prompts
To use a prompt, clients make a prompts/get request:
// Request
{
method: "prompts/get",
params: {
name: "analyze-code",
arguments: {
language: "python"
}
}
}
// Response
{
description: "Analyze Python code for potential improvements",
messages: [
{
role: "user",
content: {
type: "text",
text: "Please analyze the following Python code for potential improvements:\n\n`python\ndef calculate_sum(numbers):\n total = 0\n for num in numbers:\n total = total + num\n return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n`"
}
}
]
}
Dynamic prompts
Prompts can be dynamic and include:
Embedded resource context
{
"name": "analyze-project",
"description": "Analyze project logs and code",
"arguments": [
{
"name": "timeframe",
"description": "Time period to analyze logs",
"required": true
},
{
"name": "fileUri",
"description": "URI of code file to review",
"required": true
}
]
}
When handling the prompts/get request:
{
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Analyze these system logs and the code file for any issues:"
}
},
{
"role": "user",
"content": {
"type": "resource",
"resource": {
"uri": "logs://recent?timeframe=1h",
"text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded",
"mimeType": "text/plain"
}
}
},
{
"role": "user",
"content": {
"type": "resource",
"resource": {
"uri": "file:///path/to/code.py",
"text": "def connect_to_service(timeout=30):\n retries = 3\n for attempt in range(retries):\n try:\n return establish_connection(timeout)\n except TimeoutError:\n if attempt == retries - 1:\n raise\n time.sleep(5)\n\ndef establish_connection(timeout):\n # Connection implementation\n pass",
"mimeType": "text/x-python"
}
}
}
]
}
Multi-step workflows
const debugWorkflow = {
name: "debug-error",
async getMessages(error: string) {
return [
{
role: "user",
content: {
type: "text",
text: `Here's an error I'm seeing: ${error}`
}
},
{
role: "assistant",
content: {
type: "text",
text: "I'll help analyze this error. What have you tried so far?"
}
},
{
role: "user",
content: {
type: "text",
text: "I've tried restarting the service, but the error persists."
}
}
];
}
};
Example implementation
Here’s a complete example of implementing prompts in an MCP server:
TypeScript
Python
import { Server } from "@modelcontextprotocol/sdk/server";
import {
ListPromptsRequestSchema,
GetPromptRequestSchema
} from "@modelcontextprotocol/sdk/types";
const PROMPTS = {
"git-commit": {
name: "git-commit",
description: "Generate a Git commit message",
arguments: [
{
name: "changes",
description: "Git diff or description of changes",
required: true
}
]
},
"explain-code": {
name: "explain-code",
description: "Explain how code works",
arguments: [
{
name: "code",
description: "Code to explain",
required: true
},
{
name: "language",
description: "Programming language",
required: false
}
]
}
};
const server = new Server({
name: "example-prompts-server",
version: "1.0.0"
}, {
capabilities: {
prompts: {}
}
});
// List available prompts
server.setRequestHandler(ListPromptsRequestSchema, async () => {
return {
prompts: Object.values(PROMPTS)
};
});
// Get specific prompt
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
const prompt = PROMPTS[request.params.name];
if (!prompt) {
throw new Error(`Prompt not found: ${request.params.name}`);
}
if (request.params.name === "git-commit") {
return {
messages: [
{
role: "user",
content: {
type: "text",
text: `Generate a concise but descriptive commit message for these changes:\n\n${request.params.arguments?.changes}`
}
}
]
};
}
if (request.params.name === "explain-code") {
const language = request.params.arguments?.language || "Unknown";
return {
messages: [
{
role: "user",
content: {
type: "text",
text: `Explain how this ${language} code works:\n\n${request.params.arguments?.code}`
}
}
]
};
}
throw new Error("Prompt implementation not found");
});
Best practices
When implementing prompts:
Use clear, descriptive prompt names
Provide detailed descriptions for prompts and arguments
Validate all required arguments
Handle missing arguments gracefully
Consider versioning for prompt templates
Cache dynamic content when appropriate
Implement error handling
Document expected argument formats
Consider prompt composability
Test prompts with various inputs
UI integration
Prompts can be surfaced in client UIs as:
Slash commands
Quick actions
Context menu items
Command palette entries
Guided workflows
Interactive forms
Updates and changes
Servers can notify clients about prompt changes:
Server capability: prompts.listChanged
Notification: notifications/prompts/list_changed
Client re-fetches prompt list
Security considerations
When implementing prompts:
Validate all arguments
Sanitize user input
Consider rate limiting
Implement access controls
Audit prompt usage
Handle sensitive data appropriately
Validate generated content
Implement timeouts
Consider prompt injection risks
Document security requirements
###
Here is information for MCP Transport
###
Transports
Learn about MCP’s communication mechanisms
Transports in the Model Context Protocol (MCP) provide the foundation for communication between clients and servers. A transport handles the underlying mechanics of how messages are sent and received.
Message Format
MCP uses JSON-RPC 2.0 as its wire format. The transport layer is responsible for converting MCP protocol messages into JSON-RPC format for transmission and converting received JSON-RPC messages back into MCP protocol messages.
There are three types of JSON-RPC messages used:
Requests
{
jsonrpc: "2.0",
id: number | string,
method: string,
params?: object
}
Responses
{
jsonrpc: "2.0",
id: number | string,
result?: object,
error?: {
code: number,
message: string,
data?: unknown
}
}
Notifications
{
jsonrpc: "2.0",
method: string,
params?: object
}
Built-in Transport Types
MCP includes two standard transport implementations:
Standard Input/Output (stdio)
The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools.
Use stdio when:
Building command-line tools
Implementing local integrations
Needing simple process communication
Working with shell scripts
TypeScript (Server)
TypeScript (Client)
Python (Server)
Python (Client)
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {}
});
const transport = new StdioServerTransport();
await server.connect(transport);
Server-Sent Events (SSE)
SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication.
Use SSE when:
Only server-to-client streaming is needed
Working with restricted networks
Implementing simple updates
TypeScript (Server)
TypeScript (Client)
Python (Server)
Python (Client)
const server = new Server({
name: "example-server",
version: "1.0.0"
}, {
capabilities: {}
});
const transport = new SSEServerTransport("/message", response);
await server.connect(transport);
Custom Transports
MCP makes it easy to implement custom transports for specific needs. Any transport implementation just needs to conform to the Transport interface:
You can implement custom transports for:
Custom network protocols
Specialized communication channels
Integration with existing systems
Performance optimization
TypeScript
Python
interface Transport {
// Start processing messages
start(): Promise<void>;
// Send a JSON-RPC message
send(message: JSONRPCMessage): Promise<void>;
// Close the connection
close(): Promise<void>;
// Callbacks
onclose?: () => void;
onerror?: (error: Error) => void;
onmessage?: (message: JSONRPCMessage) => void;
}
Error Handling
Transport implementations should handle various error scenarios:
Connection errors
Message parsing errors
Protocol errors
Network timeouts
Resource cleanup
Example error handling:
TypeScript
Python
class ExampleTransport implements Transport {
async start() {
try {
// Connection logic
} catch (error) {
this.onerror?.(new Error(`Failed to connect: ${error}`));
throw error;
}
}
async send(message: JSONRPCMessage) {
try {
// Sending logic
} catch (error) {
this.onerror?.(new Error(`Failed to send message: ${error}`));
throw error;
}
}
}
Best Practices
When implementing or using MCP transport:
Handle connection lifecycle properly
Implement proper error handling
Clean up resources on connection close
Use appropriate timeouts
Validate messages before sending
Log transport events for debugging
Implement reconnection logic when appropriate
Handle backpressure in message queues
Monitor connection health
Implement proper security measures
Security Considerations
When implementing transport:
Authentication and Authorization
Implement proper authentication mechanisms
Validate client credentials
Use secure token handling
Implement authorization checks
Data Security
Use TLS for network transport
Encrypt sensitive data
Validate message integrity
Implement message size limits
Sanitize input data
Network Security
Implement rate limiting
Use appropriate timeouts
Handle denial of service scenarios
Monitor for unusual patterns
Implement proper firewall rules
Debugging Transport
Tips for debugging transport issues:
Enable debug logging
Monitor message flow
Check connection states
Validate message formats
Test error scenarios
Use network analysis tools
Implement health checks
Monitor resource usage
Test edge cases
Use proper error tracking
###
Here is information on MCP Sampling
###
Sampling
Let your servers request completions from LLMs
Sampling is a powerful MCP feature that allows servers to request LLM completions through the client, enabling sophisticated agentic behaviors while maintaining security and privacy.
This feature of MCP is not yet supported in the Claude Desktop client.
How sampling works
The sampling flow follows these steps:
Server sends a sampling/createMessage request to the client
Client reviews the request and can modify it
Client samples from an LLM
Client reviews the completion
Client returns the result to the server
This human-in-the-loop design ensures users maintain control over what the LLM sees and generates.
Message format
Sampling requests use a standardized message format:
{
messages: [
{
role: "user" | "assistant",
content: {
type: "text" | "image",
// For text:
text?: string,
// For images:
data?: string, // base64 encoded
mimeType?: string
}
}
],
modelPreferences?: {
hints?: [{
name?: string // Suggested model name/family
}],
costPriority?: number, // 0-1, importance of minimizing cost
speedPriority?: number, // 0-1, importance of low latency
intelligencePriority?: number // 0-1, importance of capabilities
},
systemPrompt?: string,
includeContext?: "none" | "thisServer" | "allServers",
temperature?: number,
maxTokens: number,
stopSequences?: string[],
metadata?: Record<string, unknown>
}
Request parameters
Messages
The messages array contains the conversation history to send to the LLM. Each message has:
role: Either “user” or “assistant”
content: The message content, which can be:
Text content with a text field
Image content with data (base64) and mimeType fields
Model preferences
The modelPreferences object allows servers to specify their model selection preferences:
hints: Array of model name suggestions that clients can use to select an appropriate model:
name: String that can match full or partial model names (e.g. “claude-3”, “sonnet”)
Clients may map hints to equivalent models from different providers
Multiple hints are evaluated in preference order
Priority values (0-1 normalized):
costPriority: Importance of minimizing costs
speedPriority: Importance of low latency response
intelligencePriority: Importance of advanced model capabilities
Clients make the final model selection based on these preferences and their available models.
System prompt
An optional systemPrompt field allows servers to request a specific system prompt. The client may modify or ignore this.
Context inclusion
The includeContext parameter specifies what MCP context to include:
"none": No additional context
"thisServer": Include context from the requesting server
"allServers": Include context from all connected MCP servers
The client controls what context is actually included.
Sampling parameters
Fine-tune the LLM sampling with:
temperature: Controls randomness (0.0 to 1.0)
maxTokens: Maximum tokens to generate
stopSequences: Array of sequences that stop generation
metadata: Additional provider-specific parameters
Response format
The client returns a completion result:
{
model: string, // Name of the model used
stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string,
role: "user" | "assistant",
content: {
type: "text" | "image",
text?: string,
data?: string,
mimeType?: string
}
}
Example request
Here’s an example of requesting sampling from a client:
{
"method": "sampling/createMessage",
"params": {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "What files are in the current directory?"
}
}
],
"systemPrompt": "You are a helpful file system assistant.",
"includeContext": "thisServer",
"maxTokens": 100
}
}
Best practices
When implementing sampling:
Always provide clear, well-structured prompts
Handle both text and image content appropriately
Set reasonable token limits
Include relevant context through includeContext
Validate responses before using them
Handle errors gracefully
Consider rate limiting sampling requests
Document expected sampling behavior
Test with various model parameters
Monitor sampling costs
Human in the loop controls
Sampling is designed with human oversight in mind:
For prompts
Clients should show users the proposed prompt
Users should be able to modify or reject prompts
System prompts can be filtered or modified
Context inclusion is controlled by the client
For completions
Clients should show users the completion
Users should be able to modify or reject completions
Clients can filter or modify completions
Users control which model is used
Security considerations
When implementing sampling:
Validate all message content
Sanitize sensitive information
Implement appropriate rate limits
Monitor sampling usage
Encrypt data in transit
Handle user data privacy
Audit sampling requests
Control cost exposure
Implement timeouts
Handle model errors gracefully
Common patterns
Agentic workflows
Sampling enables agentic patterns like:
Reading and analyzing resources
Making decisions based on context
Generating structured data
Handling multi-step tasks
Providing interactive assistance
Context management
Best practices for context:
Request minimal necessary context
Structure context clearly
Handle context size limits
Update context as needed
Clean up stale context
Error handling
Robust error handling should:
Catch sampling failures
Handle timeout errors
Manage rate limits
Validate responses
Provide fallback behaviors
Log errors appropriately
Limitations
Be aware of these limitations:
Sampling depends on client capabilities
Users control sampling behavior
Context size has limits
Rate limits may apply
Costs should be considered
Model availability varies
Response times vary
Not all content types supported
###
Here is information on building an MCP Server with Node
###
Quickstart
For Server Developers
Get started building your own server to use in Claude for Desktop and other clients.
In this tutorial, we’ll build a simple MCP weather server and connect it to a host, Claude for Desktop. We’ll start with a basic setup, and then progress to more complex use cases.
What we’ll be building
Many LLMs (including Claude) do not currently have the ability to fetch the forecast and severe weather alerts. Let’s use MCP to solve that!
We’ll build a server that exposes two tools: get-alerts and get-forecast. Then we’ll connect the server to an MCP host (in this case, Claude for Desktop):
Servers can connect to any client. We’ve chosen Claude for Desktop here for simplicity, but we also have guides on building your own client as well as a list of other clients here.
Why Claude for Desktop and not Claude.ai?
Core MCP Concepts
MCP servers can provide three main types of capabilities:
Resources: File-like data that can be read by clients (like API responses or file contents)
Tools: Functions that can be called by the LLM (with user approval)
Prompts: Pre-written templates that help users accomplish specific tasks
This tutorial will primarily focus on tools.
Python
Node
Let’s get started with building our weather server! You can find the complete code for what we’ll be building here.
Prerequisite knowledge
This quickstart assumes you have familiarity with:
TypeScript
LLMs like Claude
System requirements
For TypeScript, make sure you have the latest version of Node installed.
Set up your environment
First, let’s install Node.js and npm if you haven’t already. You can download them from nodejs.org. Verify your Node.js installation:
node --version
npm --version
For this tutorial, you’ll need Node.js version 16 or higher.
Now, let’s create and set up our project:
MacOS/Linux
Windows
# Create a new directory for our project
mkdir weather
cd weather
# Initialize a new npm project
npm init -y
# Install dependencies
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript
# Create our files
mkdir src
touch src/index.ts
Update your package.json to add type: “module” and a build script:
package.json
{
"type": "module",
"bin": {
"weather": "./build/index.js"
},
"scripts": {
"build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
},
"files": [
"build"
],
}
Create a tsconfig.json in the root of your project:
tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
Now let’s dive into building your server.
Building your server
Importing packages
Add these to the top of your src/index.ts:
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
Setting up the instance
Then initialize the NWS API base URL, validation schemas, and server instance:
const NWS_API_BASE = "https://api.weather.gov";
const USER_AGENT = "weather-app/1.0";
// Define Zod schemas for validation
const AlertsArgumentsSchema = z.object({
state: z.string().length(2),
});
const ForecastArgumentsSchema = z.object({
latitude: z.number().min(-90).max(90),
longitude: z.number().min(-180).max(180),
});
// Create server instance
const server = new Server(
{
name: "weather",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
Implementing tool listing
We need to tell clients what tools are available. This server.setRequestHandler call will register this list for us:
// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "get-alerts",
description: "Get weather alerts for a state",
inputSchema: {
type: "object",
properties: {
state: {
type: "string",
description: "Two-letter state code (e.g. CA, NY)",
},
},
required: ["state"],
},
},
{
name: "get-forecast",
description: "Get weather forecast for a location",
inputSchema: {
type: "object",
properties: {
latitude: {
type: "number",
description: "Latitude of the location",
},
longitude: {
type: "number",
description: "Longitude of the location",
},
},
required: ["latitude", "longitude"],
},
},
],
};
});
This defines our two tools: get-alerts and get-forecast.
Helper functions
Next, let’s add our helper functions for querying and formatting the data from the National Weather Service API:
// Helper function for making NWS API requests
async function makeNWSRequest<T>(url: string): Promise<T | null> {
const headers = {
"User-Agent": USER_AGENT,
Accept: "application/geo+json",
};
try {
const response = await fetch(url, { headers });
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return (await response.json()) as T;
} catch (error) {
console.error("Error making NWS request:", error);
return null;
}
}
interface AlertFeature {
properties: {
event?: string;
areaDesc?: string;
severity?: string;
status?: string;
headline?: string;
};
}
// Format alert data
function formatAlert(feature: AlertFeature): string {
const props = feature.properties;
return [
`Event: ${props.event || "Unknown"}`,
`Area: ${props.areaDesc || "Unknown"}`,
`Severity: ${props.severity || "Unknown"}`,
`Status: ${props.status || "Unknown"}`,
`Headline: ${props.headline || "No headline"}`,
"---",
].join("\n");
}
interface ForecastPeriod {
name?: string;
temperature?: number;
temperatureUnit?: string;
windSpeed?: string;
windDirection?: string;
shortForecast?: string;
}
interface AlertsResponse {
features: AlertFeature[];
}
interface PointsResponse {
properties: {
forecast?: string;
};
}
interface ForecastResponse {
properties: {
periods: ForecastPeriod[];
};
}
Implementing tool execution
The tool execution handler is responsible for actually executing the logic of each tool. Let’s add it:
// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
try {
if (name === "get-alerts") {
const { state } = AlertsArgumentsSchema.parse(args);
const stateCode = state.toUpperCase();
const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);
if (!alertsData) {
return {
content: [
{
type: "text",
text: "Failed to retrieve alerts data",
},
],
};
}
const features = alertsData.features || [];
if (features.length === 0) {
return {
content: [
{
type: "text",
text: `No active alerts for ${stateCode}`,
},
],
};
}
const formattedAlerts = features.map(formatAlert).slice(0, 20) // only take the first 20 alerts;
const alertsText = `Active alerts for ${stateCode}:\n\n${formattedAlerts.join(
"\n"
)}`;
return {
content: [
{
type: "text",
text: alertsText,
},
],
};
} else if (name === "get-forecast") {
const { latitude, longitude } = ForecastArgumentsSchema.parse(args);
// Get grid point data
const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(
4
)},${longitude.toFixed(4)}`;
const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
if (!pointsData) {
return {
content: [
{
type: "text",
text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,
},
],
};
}
const forecastUrl = pointsData.properties?.forecast;
if (!forecastUrl) {
return {
content: [
{
type: "text",
text: "Failed to get forecast URL from grid point data",
},
],
};
}
// Get forecast data
const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
if (!forecastData) {
return {
content: [
{
type: "text",
text: "Failed to retrieve forecast data",
},
],
};
}
const periods = forecastData.properties?.periods || [];
if (periods.length === 0) {
return {
content: [
{
type: "text",
text: "No forecast periods available",
},
],
};
}
// Format forecast periods
const formattedForecast = periods.map((period: ForecastPeriod) =>
[
`${period.name || "Unknown"}:`,
`Temperature: ${period.temperature || "Unknown"}°${
period.temperatureUnit || "F"
}`,
`Wind: ${period.windSpeed || "Unknown"} ${
period.windDirection || ""
}`,
`${period.shortForecast || "No forecast available"}`,
"---",
].join("\n")
);
const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join(
"\n"
)}`;
return {
content: [
{
type: "text",
text: forecastText,
},
],
};
} else {
throw new Error(`Unknown tool: ${name}`);
}
} catch (error) {
if (error instanceof z.ZodError) {
throw new Error(
`Invalid arguments: ${error.errors
.map((e) => `${e.path.join(".")}: ${e.message}`)
.join(", ")}`
);
}
throw error;
}
});
Running the server
Finally, implement the main function to run the server:
// Start the server
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Weather MCP Server running on stdio");
}
main().catch((error) => {
console.error("Fatal error in main():", error);
process.exit(1);
});
Make sure to run npm run build to build your server! This is a very important step in getting your server to connect.
Let’s now test your server from an existing MCP host, Claude for Desktop.
Testing your server with Claude for Desktop
Claude for Desktop is not yet available on Linux. Linux users can proceed to the Building a client tutorial to build an MCP client that connects to the server we just built.
First, make sure you have Claude for Desktop installed. You can install the latest version here. If you already have Claude for Desktop, make sure it’s updated to the latest version.
We’ll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at ~/Library/Application Support/Claude/claude_desktop_config.json in a text editor. Make sure to create the file if it doesn’t exist.
For example, if you have VS Code installed:
MacOS/Linux
Windows
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
You’ll then add your servers in the mcpServers key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
In this case, we’ll add our single weather server like so:
MacOS/Linux
Windows
Node
{
"mcpServers": {
"weather": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
]
}
}
}
This tells Claude for Desktop:
There’s an MCP server named “weather”
Launch it by running node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js
Save the file, and restart Claude for Desktop.
Test with commands
Let’s make sure Claude for Desktop is picking up the two tools we’ve exposed in our weather server. You can do this by looking for the hammer icon:
After clicking on the hammer icon, you should see two tools listed:
If your server isn’t being picked up by Claude for Desktop, proceed to the Troubleshooting section for debugging tips.
If the hammer icon has shown up, you can now test your server by running the following commands in Claude for Desktop:
What’s the weather in Sacramento?
What are the active weather alerts in Texas?
Since this is the US National Weather service, the queries will only work for US locations.
What’s happening under the hood
When you ask a question:
The client sends your question to Claude
Claude analyzes the available tools and decides which one(s) to use
The client executes the chosen tool(s) through the MCP server
The results are sent back to Claude
Claude formulates a natural language response
The response is displayed to you!
###
```