torna-mcp

MCP server that bridges Torna API documentation system with AI assistants (Cursor, Claude Desktop, etc.). Query, search, and explore your Torna API docs through natural language.

What it does

This server exposes Torna's API documentation as MCP tools, resources, and prompts. Your AI assistant can:

Search APIs by keyword or natural language requirement
Retrieve detailed API definitions
Generate curl command examples
Switch between projects
Access project metadata

Features

Zero-config authentication: Credentials cached per connection, no repeated input
Batch operations: Fetch multiple API details concurrently
Smart matching: Natural language requirement → matching APIs
Project switching: Switch Torna projects on the fly

Quick Start

Installation

git clone https://github.com/chenqi146/torna-mcp.git
cd torna-mcp
npm install
npm run build

Run

npm start
# Server runs on http://localhost:3000

Or with Docker:

docker build -t torna-mcp .
docker run -p 3000:3000 torna-mcp

Configure in Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "torna": {
      "transport": "http",
      "url": "http://localhost:3000/mcp",
      "heartbeat": true,
      "headers": {
        "username": "your_torna_username",
        "password": "your_torna_password",
        "projectid": "your_project_id",
        "torna-base-url": "http://your-torna-server:7700"
      }
    }
  }
}

Restart Cursor and select the torna MCP server.

Usage Examples

Find APIs by requirement

You: "I need an API to query user information"

AI: Uses torna-find-apis-by-need to match APIs, returns:

User detail API (/api/user/detail)
User list API (/api/user/list)

Search by keyword

You: "Find all APIs related to 'parking'"

AI: Uses torna-search-docs with keyword "parking", returns matching APIs.

Get API details

You: "Get details for these three APIs: JzAM4Mzp,AbC123Xy,Def456Za"

AI: Uses torna-get-doc-detail with comma-separated docIds, fetches all concurrently.

Switch projects

You: "What projects are available? Switch to user-center project"

AI: Lists projects via torna-list-projects, switches via torna-select-project.

Generate curl command

You: "Generate a curl command for the user detail API"

AI: Uses torna-generate-request to produce a ready-to-use curl command.

MCP Tools

All tools automatically use cached authentication from connection headers.

| Tool | Description | |------|-------------| | torna-project-info | Get current session info (username, project ID/name, token status, doc count) | | torna-search-docs | Search APIs by keyword. Returns full tree if keyword is empty | | torna-get-doc-detail | Get API detail(s). Supports single or comma-separated docIds (batch, concurrent) | | torna-list-projects | List all accessible spaces/projects | | torna-select-project | Switch active project for subsequent operations |

MCP Resources

config://settings - Server configuration example
torna://session/project - Current session project info
torna://projects - Real-time project list

MCP Prompts

torna-find-apis-by-need - Find APIs matching a natural language requirement. Auto-fetches details for projects with ≤30 APIs for better matching.
torna-generate-request - Generate curl command from API definition

Development

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Production
npm start

Environment Variables

PORT - Server port (default: 3000)
MCP_URL - MCP server base URL (default: http://localhost:3000)

Logging

[TornaExternal] - Actual Torna API requests/responses
[TornaAPI] - MCP responses to clients
[MCPAuth] - Authentication events
[MCPCapture] - MCP request capture

Architecture

AI Assistant (Cursor/Claude) 
    ↓ MCP Protocol
torna-mcp Server (this project)
    ↓ HTTP Proxy
Torna API Server

The server acts as a proxy between MCP clients and Torna, handling:

Authentication (login, token caching)
Request routing (MCP tools → Torna endpoints)
Response transformation (Torna format → MCP format)

Contributing

Fork the repository
Create a feature branch
Make changes
Submit a pull request

Keep it simple. No unnecessary abstractions.

License

MIT

MCP Servers