typingmind-mcp

# MCP Connector **MCP Connector** is a lightweight server that can run and manage multiple Model Context Protocol (MCP) servers, specifically designed to integrate with [TypingMind](https://www.typingmind.com/mcp). It provides an easy way to run MCP servers on your local computer or a remote server, making it possible to connect your custom AI models or tools with TypingMind through a simple REST API. --- ## How to Run on Your Local Device You can quickly start the MCP Connector using `npx` (no install required): ```bash npx @typingmind/mcp@latest <auth-token> ``` - Replace `<auth-token>` with your authentication token provided by TypingMind. You can also provide the auth token via an environment variable: ```bash MCP_AUTH_TOKEN=<auth-token> npx @typingmind/mcp@latest ``` Keep the process running while you use TypingMind. ### HTTPS Support To enable HTTPS, set the following environment variables: ```bash CERTFILE=./path/to/certificate.crt KEYFILE=./path/to/privatekey.key npx @typingmind/mcp@latest <auth-token> ``` - `CERTFILE`: Path to your SSL certificate file - `KEYFILE`: Path to your SSL private key file When both variables are set, the server will use HTTPS instead of HTTP. --- ## How to Run on a Server If you prefer running the MCP Connector on a remote server: 1. **Install Node.js** (version 14 or later). 2. Run the server using `npx`: ```bash npx @typingmind/mcp@latest <auth-token> ``` To run with HTTPS: ```bash CERTFILE=./path/to/certificate.crt KEYFILE=./path/to/privatekey.key npx @typingmind/mcp@latest <auth-token> ``` Alternatively, for persistent running (e.g., after closing SSH), you may use a process manager like [pm2](https://pm2.keymetrics.io/) or `screen`/`tmux`: ```bash pm2 start npx -- @typingmind/mcp@latest <auth-token> ``` --- ## How to Run with Docker You can also run the MCP Connector using Docker. 1. **Build the Docker Image:** Navigate to the project's root directory (where the `Dockerfile` is located) and run: ```bash docker build -t mcp-connector . ``` _(You can replace `mcp-connector` with your preferred image tag.)_ 2. **Run the Docker Container:** - **Basic Run (HTTP):** Replace `<auth-token>` with your actual token. This command runs the container in detached mode (`-d`) and maps the container's default port `50880` to the same port on your host machine. ```bash docker run -d -p 50880:50880 --name mcp-connector-instance mcp-connector <auth-token> ``` - **Using a Different Port:** If you need to use a different port (e.g., 8080 on the host mapped to 12345 in the container), use the `-p` flag for mapping and the `-e PORT` environment variable: ```bash docker run -d -p 8080:12345 -e PORT=12345 --name mcp-connector-instance mcp-connector <auth-token> ``` - **Running with HTTPS:** To enable HTTPS, you need to provide the certificate and key files and set the `CERTFILE` and `KEYFILE` environment variables. Mount your host's certificate files into the container (e.g., into a `/certs` directory) and provide the paths via environment variables. Remember to map the appropriate port. ```bash docker run -d \ -p 50880:50880 \ -e PORT=50880 \ -e CERTFILE=/certs/certificate.crt \ -e KEYFILE=/certs/privatekey.key \ -v /path/to/your/certificate.crt:/certs/certificate.crt:ro \ -v /path/to/your/privatekey.key:/certs/privatekey.key:ro \ --name mcp-connector-instance \ mcp-connector <auth-token> ``` _(Replace `/path/to/your/certificate.crt` and `/path/to/your/privatekey.key` with the actual paths on your host machine. The `:ro` flag mounts them as read-only.)_ - **Viewing Logs:** To see the logs from the running container: ```bash docker logs mcp-connector-instance ``` - **Stopping the Container:** ```bash docker stop mcp-connector-instance ``` - **Removing the Container:** ```bash docker rm mcp-connector-instance ``` --- ## How to Connect to TypingMind To connect MCP Connector to TypingMind: 1. Follow the instructions at [www.typingmind.com/mcp](https://www.typingmind.com/mcp). 2. Paste your MCP Connector server address (`http://localhost:<port>` or your server’s IP address and port) and your authentication token on the TypingMind MCP integration page. --- ## Configuring Tool Call Timeout You can set a custom timeout for tool calls (in milliseconds) using the `TIMEOUT` environment variable: ```bash # Set timeout to 2 minutes (120000ms) TIMEOUT=120000 npx @typingmind/mcp@latest <auth-token> # Or combine with auth token environment variable TIMEOUT=120000 MCP_AUTH_TOKEN=<auth-token> npx @typingmind/mcp@latest # Default timeout is 60 seconds (60000ms) if not specified npx @typingmind/mcp@latest <auth-token> ``` --- ## REST API Endpoints All API endpoints require authentication via the Bearer token you provide when starting the server. | Endpoint | Method | Description | | ------------------------- | ------ | -------------------------------------------------------------- | | `/ping` | GET | Health check; returns `{ status: "ok" }` | | `/start` | POST | Start one or more MCP clients; body: `{ mcpServers: { ... } }` | | `/restart/:id` | POST | Restart a specific client | | `/clients` | GET | List all running MCP clients and their tools | | `/clients/:id` | GET | Get info about a specific client | | `/clients/:id/tools` | GET | List available tools for a client | | `/clients/:id/call_tools` | POST | Call a tool for a client; body: `{ name, arguments }` | | `/clients/:id` | DELETE | Stop and delete a client | | `/mcp-connect` | POST | Proxy fetch requests; body: `{ url, options? }` | **Notes:** - All requests need an `Authorization: Bearer <auth-token>` header. - Available ports: The server will choose port `50880` or `50881`, make sure these ports are available in your system. You can also use `PORT` environment variable to specify a different port. ### `/mcp-connect` Endpoint The `/mcp-connect` endpoint acts as a proxy for fetch requests, allowing you to make HTTP requests through the MCP Connector server. This is useful for connecting to remote MCP servers or making cross-origin requests. **Request Body:** - `url` (required): The URL to fetch - `options` (optional): Fetch options object (method, headers, body, etc.) **Response:** - The endpoint streams the response from the target URL, including status code, headers, and body - Certain headers are filtered out to prevent decoding issues (Content-Encoding, Content-Length, Transfer-Encoding, and CORS headers) - All proxied headers are exposed via `Access-Control-Expose-Headers` for CORS compatibility **Example:** ```bash curl -X POST http://localhost:50880/mcp-connect \ -H "Authorization: Bearer <auth-token>" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/api/endpoint", "options": { "method": "POST", "headers": { "Content-Type": "application/json" }, "body": "{\"key\": \"value\"}" } }' ``` --- ## License MIT