# torna-mcp

MCP server that bridges [Torna](https://gitee.com/durcframework/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

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

### Run

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

Or with Docker:

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

### Configure in Cursor

Add to `~/.cursor/mcp.json`:

```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

```bash
# 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