api-tool-mcp

API CALLER MCP SERVER
=====================

Universal API caller MCP server supporting all HTTP methods, WebSocket connections, and multiple content types.
A complete API testing tool similar to Postman, built as an MCP package.

FEATURES
--------
- All HTTP methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
- HTTP and HTTPS protocols
- WebSocket support (ws:// and wss://)
- Multiple body types: JSON, form-data, urlencoded, raw, binary
- File uploads with multipart/form-data
- Image uploads with custom filenames and content types
- Custom headers for all requests
- Query parameters support
- Request timeout control
- Comprehensive error handling
- WebSocket message history and connection management
- Multiple simultaneous WebSocket connections

INSTALLATION
------------

After publishing to npm:

npm install -g @your-scope/package-name

Or use directly with npx (recommended for MCP):

npx -y @your-scope/package-name

CONFIGURATION
-------------

Add to your MCP settings:

{
"mcpServers": {
"api-caller": {
"command": "npx",
"args": ["-y", "@your-scope/package-name"]
}
}
}

AVAILABLE TOOLS
---------------

HTTP Tools:
- http_request: Full control HTTP request (any method)
- http_get: GET request
- http_post: POST request (any body type)
- http_post_json: POST with JSON body
- http_post_form: POST with multipart/form-data (file uploads)
- http_post_urlencoded: POST with x-www-form-urlencoded
- http_put: PUT request
- http_patch: PATCH request
- http_delete: DELETE request

WebSocket Tools:
- websocket_connect: Connect to WebSocket
- websocket_send: Send message through connection
- websocket_receive: Get received messages
- websocket_close: Close connection
- websocket_info: Get connection details
- websocket_list: List all active connections

BODY TYPES
----------
- json: application/json
- form / multipart: multipart/form-data (for file uploads)
- urlencoded: application/x-www-form-urlencoded
- raw / text: text/plain
- binary: application/octet-stream

USAGE EXAMPLES
--------------

Simple GET request:
{
"url": "https://api.github.com/users/github"
}

GET with headers and query params:
{
"url": "https://api.example.com/search",
"headers": {
"Authorization": "Bearer YOUR_TOKEN",
"Accept": "application/json"
},
"queryParams": {
"q": "nodejs",
"limit": 10
}
}

POST JSON data:
{
"url": "https://api.example.com/users",
"body": {
"name": "John Doe",
"email": "john@example.com"
},
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}

POST form-urlencoded:
{
"url": "https://api.example.com/login",
"data": {
"username": "user",
"password": "pass"
}
}

Upload file with multipart form:
{
"url": "https://api.example.com/upload",
"fields": {
"title": "My Image",
"description": "An example image",
"image": {
"file": "/absolute/path/to/image.jpg",
"filename": "photo.jpg",
"contentType": "image/jpeg"
}
}
}

POST binary data:
{
"url": "https://api.example.com/binary",
"body": "/path/to/file.bin",
"bodyType": "binary"
}

WebSocket connection:
{
"url": "wss://echo.websocket.org",
"connectionId": "my-connection",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}

Send WebSocket message:
{
"connectionId": "my-connection",
"message": "Hello WebSocket!"
}

Get WebSocket messages:
{
"connectionId": "my-connection",
"limit": 10,
"offset": 0
}

ERROR HANDLING
--------------

All errors return structured JSON responses:

{
"success": false,
"error": {
"message": "Error description",
"statusCode": 404,
"details": {},
"timestamp": "2024-01-30T12:00:00.000Z"
}
}

SUCCESSFUL RESPONSE
-------------------

{
"success": true,
"request": {
"method": "POST",
"url": "https://api.example.com/endpoint",
"headers": {...},
"bodyType": "json"
},
"response": {
"status": 200,
"statusText": "OK",
"headers": {...},
"body": {...}
},
"metadata": {
"duration": "145ms",
"timestamp": "2024-01-30T12:00:00.000Z"
}
}

REQUIREMENTS
------------
- Node.js >= 18.0.0

PUBLISHING
----------

1. Update package.json with your package name
2. npm login
3. npm publish --access public

LICENSE
-------
MIT License - See LICENSE file for details