Enhance API tools and documentation for Postman integration #2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The Postman API requires environment IDs to be in the format
{ownerId}-{environmentId}. This update adds proper handling and
validation of environment UIDs throughout the codebase:
* Add constructEnvironmentUid helper to consistently create UIDs
* Update isValidUid to properly validate numeric owner ID + UUID format
* Transform API responses to include properly constructed UIDs
* Add descriptive error messages about expected UID format
* Update tool schemas with clear format requirements and examples
* Ensure all environment operations validate and use full UID format
This change improves error handling and provides better guidance to
users about the required environment ID format, while maintaining
compatibility with the Postman API's security requirements around
environment access.
1. Adding resources and prompts capabilities to the server configuration
2. Implementing ListResourcesRequestSchema handler that exposes:
- Static resources for workspaces and user info
- URIs like 'postman://workspaces' and 'postman://user'
3. Implementing ListResourceTemplatesRequestSchema handler that exposes:
- Dynamic resources for workspace collections and environments
- URI templates like 'postman://workspaces/{workspaceId}/collections'
4. Implementing ListPromptsRequestSchema handler that exposes:
- Prompts for creating collections with endpoints
- Prompts for creating environments with variables
NOTE: These endpoints are incomplete and will be extended once we have
an idea how we want this MCP service to be used.
Move tool definitions from PostmanAPIServer to their respective tool handler classes. Each tool class now implements getToolDefinitions() to expose its own interface, following the single responsibility principle. This change: - Reduces duplication in tool definitions and implementations - Makes it easier to add and maintain tools - Improves code organization by co-locating related functionality - Simplifies the main server class by delegating tool management The refactoring includes: - Moving PostmanAPIServer to its own file - Breaking down setupHandlers into focused methods - Adding getToolDefinitions() to all tool classes - Updating server to aggregate tool definitions from handlers
Properly handles all collection operations according to the Postman API documentation, including: Creating collections with proper schema validation Updating collections with full replacement Forking collections with proper workspace handling Proper request/response body schemas for all operations
…and UserTools) correctly implement the ToolHandler interface with: axiosInstance property for making API requests getToolDefinitions() method for declaring available tools handleToolCall() method for executing tool operations The codebase successfully implements the improvements for: Using a Map to cache tool handlers Improved error handling with McpError types Centralized tool definition management Simplified tool call routing logic
Did not get to: * Mocks * Monitors * Auth * Security features
Enhances reference documentation with usage guides and links with comprehensive sections covering all Postman API features: - Adds authentication guides and best practices - Includes links to official Postman docs and workspaces - Improves code block formatting from bash to prompt - Clarifies reference file organization and usage Makes documentation more accessible and maintainable by providing clear cross-references between implementation and API specifications.
Based on their logical groupings: tool.ts - Core MCP tool-related types common.ts - Common argument types and their type guards collection.ts - Collection-related types and type guards environment.ts - Environment-related types and type guards validation.ts - Validation utility function index.ts - Re-exports all types from their respective modules
- Remove redundant type validation and guards - Consolidate error handling to auth-only at top level - Remove response transformations in favor of direct API responses - Simplify method signatures to reduce type complexity - Remove unused utility methods and transformations This change reduces code complexity and maintenance burden by letting the underlying API handle validation and transformations. The simplified implementation maintains all existing functionality while being more maintainable.
• Simplified error handling and validation • Removed redundant type guards • Consolidated response formatting • Streamlined API method implementations • Reduced code duplication
• Consolidated duplicate API call patterns • Simplified request/response handling • Streamlined type definitions • Reduced error handling boilerplate • Added common base types for params
• Streamlined API response handling • Simplified type definitions • Removed redundant type guards • Consolidated error handling • Improved code organization
• Added API-specific type enums • Improved error handling for API responses • Added input validation for API methods • Enhanced documentation and JSDoc comments • Updated schema and version type definitions
• Add get_api_collection endpoint • Add get_api_schema endpoint • Add get_task_status endpoint • Add comment length validation • Standardize API version header usage
• Added auth tools implementation for managing access keys, roles, and user authentication • Created auth type definitions • Added base Postman API tool class • Added zod validation package • Added auth tool definitions
- Add mock server API tool definitions - Create mock server tool handlers - Support full CRUD operations for mocks - Add server response management - Update tool exports and organization
• Add monitor tool definitions and schemas for managing Postman monitoring services • Implement monitor CRUD operations • Add monitor run functionality • Export monitor tools from API module • Handle error scenarios for monitor calls
- Implement billing account tools - Add comment resolution functionality - Support private API network operations - Create webhook management tools - Add workspace tag management features
• Added all collection CRUD endpoints and item management • Added folder/request/response management • Enhanced error handling and types • Aligned with Postman API specs • Made workspace param optional
- extend BasePostmanTool for shared features - standardize error handling & responses - improve type safety & documentation - simplify validation & param checking - add v10 accept header handling
• Remove exposed axiosInstance from interface • Simplify client initialization • Make client property readonly • Add null check for apiKey • Update tool handler docs
• Extend BasePostmanTool in all API classes • Add input validation for required params • Standardize error handling patterns • Clean up constructor signatures • Remove redundant error handling code
• Move handlers to dedicated files • Improve code structure and readability • Create new handlers directory • Extract handler classes from server.ts • Update version to 0.2.0
• Added API resource handlers • Created request validation & types • Set up API endpoint mapping • Added error handling • Implemented resource templating
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Introduce improved handling and validation for environment UIDs, implement new resources and prompts endpoints, and refactor tool definitions for better organization and maintainability. Update documentation to clarify usage and requirements, while simplifying API tools and enhancing error handling across the codebase.