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

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Submit a pull request

Keep it simple. No unnecessary abstractions.

License

MIT