# 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
