README.md•32.7 kB
# Theneo MCP Server
**Model Context Protocol server for Theneo SDK** - The automation backbone for API documentation in the AI era.
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://github.com/atombreak/theneo-mcp/actions)
<!-- Uncomment when services are live -->
<!-- [](https://www.npmjs.com/package/theneo-mcp) -->
<!-- [](https://codecov.io/gh/theneo/theneo-mcp) -->
<!-- [](https://hub.docker.com/r/theneo/theneo-mcp) -->
This MCP server exposes [Theneo's](https://theneo.io) API documentation platform through the [Model Context Protocol](https://modelcontextprotocol.io/), allowing AI assistants to create, update, and publish API documentation automatically.
## Overview
Theneo MCP enables any AI assistant (Claude Desktop, VS Code Copilot, Cursor, etc.) to interact with Theneo's SDK, making API documentation creation and maintenance fully automatable. Perfect for CI/CD pipelines, AI-driven workflows, and developer productivity tools.
### Key Features
- 💬 **Natural Language**: Just talk—no need to memorize tool names or parameters!
- 🎯 **Name-Based References**: Reference projects and workspaces by name instead of IDs—AI looks them up automatically!
- 🤖 **AI-First**: Works with any MCP-compatible AI assistant (Claude, VS Code, Cursor)
- 🔐 **Enterprise Security**: Multi-source config, OS keychain support, secret masking
- 🛠️ **15 Powerful Tools**: Complete project lifecycle management—workspaces, projects, versions, exports, and more
- 📦 **Flexible Input**: Supports OpenAPI/Swagger files, URLs, raw text, and Postman collections
- 🚀 **AI-Powered**: Built-in AI description generation (fill, overwrite, or skip)
- 🔄 **Smart Imports**: Merge, overwrite, or endpoints-only update strategies
- 🌍 **Profile Support**: Manage multiple environments (dev, staging, prod)
## Design Choices
### Why SDK Over CLI?
Direct SDK integration provides type safety, better error handling, and access to the full API surface without shell escaping issues.
### Why OS Keychain?
Secure at-rest storage for credentials without environment variables or plain-text files. Cross-platform support via keytar.
### Why Profile Support?
Multi-environment workflows (dev/staging/prod) are common. Profiles allow easy context switching without credential juggling.
### Why MCP Protocol?
MCP standardizes AI-tool integration. Write once, works with Claude, VS Code Copilot, Cursor, and future AI assistants.
## Installation
### npm (Recommended)
```bash
# Global installation
npm install -g theneo-mcp
# Verify installation
theneo-mcp --version
```
### Homebrew (macOS/Linux)
```bash
# Add tap
brew tap theneo/theneo-mcp
# Install
brew install theneo-mcp
# Verify installation
theneo-mcp --version
```
### Docker
```bash
# Pull from Docker Hub
docker pull theneo/theneo-mcp:latest
# Run with API key
docker run -it --rm \
-e THENEO_API_KEY=your_api_key \
theneo/theneo-mcp:latest
```
See [DOCKER.md](DOCKER.md) for detailed Docker usage.
### Local Development
```bash
git clone https://github.com/atombreak/theneo-mcp.git
cd theneo-mcp
npm install
npm run build
```
## Quick Start (5 Minutes)
### 1. Get Your API Key
Visit [https://app.theneo.io/](https://app.theneo.io/) to get your Theneo API key.
### 2. Configure Authentication
**Option A: OS Keychain (Recommended for local dev)**
```bash
theneo-mcp creds save --profile default --apiKey YOUR_API_KEY
```
**Option B: Environment Variable**
```bash
export THENEO_API_KEY=YOUR_API_KEY
```
### 3. Connect to Your AI Assistant
#### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"theneo": {
"command": "theneo-mcp",
"args": ["server"]
}
}
}
```
#### VS Code Copilot
Add to your VS Code `settings.json`:
```json
{
"chat.mcp.access": "all",
"chat.mcp.servers": {
"theneo": {
"command": "theneo-mcp",
"args": ["server"],
"env": {
"THENEO_API_KEY": "your_api_key_here"
}
}
}
}
```
#### Cursor
Add to Cursor settings (Settings → MCP):
```json
{
"mcpServers": {
"theneo": {
"command": "theneo-mcp",
"args": ["server", "--profile", "default"]
}
}
}
```
### 4. Test It Out
In your AI assistant, just talk naturally:
```
Show me my Theneo workspaces
```
Then create a project:
```
Create a new project called "Demo API" using the Petstore OpenAPI example
from GitHub. Make it public and enable AI descriptions.
```
Or if you prefer being explicit:
```
Use theneo_create_project with name "Demo API",
link "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json",
publish true, isPublic true, and descriptionGeneration "FILL"
```
💡 **Pro tip**: You don't need to memorize tool names or parameters—just describe what you want in plain English!
## Configuration
### Configuration Sources & Precedence
Configuration is loaded from multiple sources with clear precedence (highest first):
| Priority | Source | Use Case | Example |
|----------|--------|----------|---------|
| 1 | CLI flags | Override everything | `--apiKey sk_xxx` |
| 2 | Environment variables | CI/CD, containers | `THENEO_API_KEY=xxx` |
| 3 | Project RC file | Project-specific settings | `.theneo-mcp.yaml` |
| 4 | User config | Personal defaults | `~/.config/theneo-mcp/config.json` |
| 5 | OS keychain | Secure local storage | `theneo-mcp creds save` |
| 6 | .env file | Development only | `.env` |
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `THENEO_API_KEY` | Your Theneo API key | *Required* |
| `THENEO_BASE_API_URL` | Theneo API endpoint | `https://api.theneo.io` |
| `THENEO_BASE_APP_URL` | Theneo web app URL | `https://app.theneo.io` |
| `THENEO_PROFILE` | Configuration profile | `default` |
### Project Configuration File
Create `.theneo-mcp.yaml` or `.theneo-mcp.json` in your project root:
```yaml
# .theneo-mcp.yaml
profile: default
baseApiUrl: https://api.theneo.io
baseAppUrl: https://app.theneo.io
# Multi-environment support
profiles:
development:
profile: development
production:
profile: production
```
**⚠️ Security Note**: Never commit API keys to version control! Store them in keychain or environment variables.
### User Configuration
Create `~/.config/theneo-mcp/config.json` (Linux/macOS) or `%AppData%/theneo-mcp/config.json` (Windows):
```json
{
"profile": "default",
"baseApiUrl": "https://api.theneo.io",
"baseAppUrl": "https://app.theneo.io",
"profiles": {
"default": {},
"production": {}
}
}
```
### OS Keychain (Recommended)
Store API keys securely in your system's keychain:
```bash
# Save API key
theneo-mcp creds save --profile default --apiKey YOUR_KEY
# Remove API key
theneo-mcp creds rm --profile default
# List stored profiles
theneo-mcp creds list
```
### Using Profiles
Switch between environments easily:
```bash
# Use production profile
theneo-mcp server --profile production
# Or via environment
THENEO_PROFILE=production theneo-mcp server
```
## Available Tools
💡 **Tip**: You don't need to use the exact tool names! Just talk naturally to your AI assistant, and it will figure out which tool to call.
🎯 **New**: You can now reference **projects** and **workspaces** by **name** instead of remembering their IDs! The AI will automatically look them up for you.
### 1. `theneo_list_workspaces`
List all workspaces accessible to your account.
**Parameters:** None
**Natural Language Examples:**
```
Show me my Theneo workspaces
What workspaces do I have access to?
List all my Theneo workspaces
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_list_workspaces
```
### 2. `theneo_list_projects`
List all projects in a workspace or across all workspaces. You can filter by workspace using ID, key (slug), or name. Returns project names, IDs, and details.
**Parameters:**
- `workspaceId` (string, optional): Workspace ID to filter projects
- `workspaceKey` (string, optional): Workspace key/slug to filter projects
- `workspaceName` (string, optional): Workspace name to filter projects
**Natural Language Examples:**
```
Show me all my projects
List all projects in the "Engineering" workspace
What projects do I have in my "Production" workspace?
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_list_projects
```
### 3. `theneo_create_project`
Create a new API documentation project with optional spec import and AI generation. You can specify the workspace by ID, key (slug), or name.
**Parameters:**
- `name` (string, required): Project name
- `workspaceKey` (string, optional): Workspace slug
- `workspaceId` (string, optional): Workspace ID
- `workspaceName` (string, optional): Workspace name
- `publish` (boolean, optional): Publish immediately
- `isPublic` (boolean, optional): Make project public
- `descriptionGeneration` (enum, optional): `FILL` | `OVERWRITE` | `NO_GENERATION`
- **Data sources** (choose one):
- `file` (string): Path to local OpenAPI/Swagger file
- `link` (string): URL to OpenAPI/Swagger spec
- `text` (string): Raw OpenAPI/Swagger spec
- `postmanApiKey` + `postmanCollectionIds`: Import from Postman
**Natural Language Examples:**
```
Create a new project called "Payment API" in the "Engineering" workspace from
this OpenAPI spec: https://example.com/openapi.json and make it public with AI descriptions
I need to create API documentation for my REST API in my "Production" workspace.
The spec is at ./specs/api.yaml. Name it "User Service API" and enable AI descriptions.
Can you create a Theneo project named "Stripe Clone" in the "Public APIs" workspace
using the Petstore example from GitHub? Make it public and publish it immediately.
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_create_project with:
- name: "My API"
- link: "https://example.com/openapi.json"
- publish: true
- isPublic: true
- descriptionGeneration: "FILL"
```
**Example Response:**
```json
{
"projectId": "proj_abc123xyz",
"publishData": {
"projectKey": "my-api",
"companySlug": "acme-corp",
"publishedPageUrl": "https://app.theneo.io/acme-corp/my-api",
"baseUrlRequired": false
}
}
```
### 4. `theneo_import_project_document`
Import or update API documentation in an existing project. **You can reference both the project and workspace by name instead of IDs**.
**Parameters:**
- `projectId` (string, optional): Target project ID
- `projectName` (string, optional): Target project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
- `publish` (boolean, optional): Publish after import
- `importOption` (enum, optional): `MERGE` | `OVERWRITE` | `ENDPOINTS_ONLY`
- **Data sources** (same as create_project, one required)
**Natural Language Examples:**
```
Update the "Payment API" project in my "Engineering" workspace with the latest
spec from ./api/openapi.yaml and merge it with existing content
I need to import a new version into the "User Service" project in the "Production"
workspace. Use this URL: https://api.example.com/openapi.json and overwrite everything.
Import the updated Postman collection into "My Company API" in the "Public APIs"
workspace and publish it with merge.
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_import_project_document with:
- projectId: "proj_123"
- file: "./openapi.json"
- importOption: "MERGE"
- publish: true
```
### 5. `theneo_publish_project`
Publish a project to make it live. **You can reference both project and workspace by name**. Optionally specify a version to publish.
**Parameters:**
- `projectId` (string, optional): Project ID
- `projectName` (string, optional): Project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
- `versionId` (string, optional): Version ID to publish (publishes default version if not specified)
**Natural Language Examples:**
```
Publish the "Payment API" project in my "Engineering" workspace
Make the "User Service API" in the "Production" workspace live
Publish the project called "Stripe Clone" in "Public APIs"
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_publish_project with projectId "proj_123"
```
### 6. `theneo_preview_link`
Get the editor preview URL for a project. **You can reference both project and workspace by name**.
**Parameters:**
- `projectId` (string, optional): Project ID
- `projectName` (string, optional): Project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
**Natural Language Examples:**
```
Get me the preview link for "Payment API" in the "Engineering" workspace
Show me where I can edit the "User Service" project in "Production"
What's the URL to view "My Company API" in the "Public APIs" workspace?
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_preview_link for project "proj_123"
```
### 7. `theneo_wait_for_generation`
Wait for AI description generation to complete. **You can reference both project and workspace by name**.
**Parameters:**
- `projectId` (string, optional): Project ID
- `projectName` (string, optional): Project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
- `retryTimeMs` (number, optional): Polling interval (default: 2500)
- `maxWaitTimeMs` (number, optional): Max wait time (default: 120000)
**Natural Language Examples:**
```
Wait for the AI to finish generating descriptions for "Payment API" in "Engineering"
Check if AI generation is complete for "User Service" in the "Production" workspace
Keep checking until the AI descriptions are done for "My Company API" in "Public APIs"
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_wait_for_generation for project "proj_123"
```
### 8. `theneo_get_generation_status`
Get the current status and progress of AI description generation for a project. **You can reference both project and workspace by name**.
**Parameters:**
- `projectId` (string, optional): Project ID
- `projectName` (string, optional): Project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
**Natural Language Examples:**
```
Check the AI generation status for "Payment API" in "Engineering"
What's the progress of AI description generation for "User Service"?
Show me the generation status of "My Company API" in the "Public APIs" workspace
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_get_generation_status with projectId "proj_123"
```
### 9. `theneo_delete_project`
Permanently delete a project. **You can reference both project and workspace by name**. ⚠️ This action cannot be undone.
**Parameters:**
- `projectId` (string, optional): Project ID
- `projectName` (string, optional): Project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
**Natural Language Examples:**
```
Delete the "Old API" project from my "Engineering" workspace
I need to remove the "Test Project" from the "Staging" workspace
Can you delete "Legacy API v1" in my "Production" workspace?
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_delete_project with projectId "proj_123"
```
### 10. `theneo_list_project_versions`
List all versions of a specific project. **You can reference both project and workspace by name**.
**Parameters:**
- `projectId` (string, optional): Project ID
- `projectName` (string, optional): Project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
**Natural Language Examples:**
```
Show me all versions of the "Payment API" project in "Engineering"
List versions for "User Service" in the "Production" workspace
What versions does the "My Company API" have?
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_list_project_versions with projectId "proj_123"
```
### 11. `theneo_create_project_version`
Create a new version of a project. **You can reference both project and workspace by name**.
**Parameters:**
- `name` (string, required): Version name
- `projectId` (string, optional): Project ID
- `projectName` (string, optional): Project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
- `previousVersionId` (string, optional): Previous version ID to copy from
- `isNewVersion` (boolean, optional): Whether this is a new version
- `isEmpty` (boolean, optional): Whether the version should be empty
- `isDefault` (boolean, optional): Whether this should be the default version
**Natural Language Examples:**
```
Create a new version "v2.0" for "Payment API" in the "Engineering" workspace
Add version "2024-Q1" to the "User Service" project in "Production"
Create an empty version called "v3.0-beta" for "My Company API"
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_create_project_version with:
- name: "v2.0"
- projectId: "proj_123"
```
### 12. `theneo_delete_project_version`
Delete a specific version of a project. ⚠️ This action cannot be undone.
**Parameters:**
- `versionId` (string, required): Version ID to delete
**Natural Language Examples:**
```
Delete version "ver_abc123" from the project
Remove the beta version with ID ver_xyz789
I need to delete version ver_old456
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_delete_project_version with versionId "ver_123"
```
### 13. `theneo_add_subscriber_to_version`
Add an email subscriber to receive updates for a specific project version.
**Parameters:**
- `email` (string, required): Email address to subscribe
- `projectVersionId` (string, required): Project version ID
**Natural Language Examples:**
```
Add john@company.com as a subscriber to version ver_abc123
Subscribe jane.doe@example.com to receive updates for version ver_xyz789
I want to add team@company.com to the subscriber list for version ver_def456
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_add_subscriber_to_version with:
- email: "user@example.com"
- projectVersionId: "ver_123"
```
### 14. `theneo_export_project`
Export a project's documentation. **You can reference both project and workspace by name**.
**Parameters:**
- `projectId` (string, optional): Project ID
- `projectName` (string, optional): Project name (alternative to projectId)
- `workspaceId` (string, optional): Workspace ID (helps when using projectName)
- `workspaceKey` (string, optional): Workspace key/slug (helps when using projectName)
- `workspaceName` (string, optional): Workspace name (helps when using projectName)
- `versionId` (string, optional): Version ID to export
- `dir` (string, optional): Directory to save export
- `noGeneration` (boolean, optional): Skip AI generation
- `shouldGetPublicViewData` (boolean, optional): Get public view data
- `openapi` (boolean, optional): Export as OpenAPI format
**Natural Language Examples:**
```
Export the "Payment API" project from the "Engineering" workspace as OpenAPI
Download the documentation for "User Service" in "Production" to ./exports
Export "My Company API" with public view data
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_export_project with:
- projectId: "proj_123"
- openapi: true
```
### 15. `theneo_list_postman_collections`
List all Postman collections accessible with a provided Postman API key.
**Parameters:**
- `postmanApiKey` (string, required): Postman API key
**Natural Language Examples:**
```
Show me my Postman collections using this API key: pmak_xyz123
List all Postman collections I have access to
What Postman collections are available with my API key?
```
**Explicit Tool Call (for testing/debugging):**
```
Use theneo_list_postman_collections with postmanApiKey "pmak_xyz123"
```
## Demo Script (End-to-End)
This 5-minute demo shows the complete workflow. You can use either **natural language** or **explicit tool calls**.
### 🗣️ Natural Language Version (Recommended)
Just talk naturally to your AI assistant:
```
Step 1: Show me my Theneo workspaces
Step 2: Create a new project called "USPTO API Documentation" using this OpenAPI spec:
https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/uspto.json
Make it public, publish it immediately, and enable AI-generated descriptions to fill in missing content.
Step 3: Wait for the AI description generation to complete for that project
Step 4: Get me the preview link so I can view it in the editor
Step 5: Now update the project with the local file ./examples/sample-openapi.json
and merge it with the existing content, then publish it
Step 6: Finally, publish the project and show me the published URL
```
### 🔧 Explicit Tool Calls Version (For Testing)
If you want precise control or are debugging:
```
Step 1: List workspaces
Use theneo_list_workspaces
Step 2: Create a project with AI generation
Use theneo_create_project with:
- name: "USPTO API Documentation"
- link: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/uspto.json"
- publish: true
- isPublic: true
- descriptionGeneration: "FILL"
Step 3: Wait for AI to finish
Use theneo_wait_for_generation with the project ID from step 2
Step 4: Get the preview link
Use theneo_preview_link with the project ID
Step 5: Import an update (merge mode)
Use theneo_import_project_document with:
- projectId: (from step 2)
- file: "./examples/sample-openapi.json"
- importOption: "MERGE"
- publish: true
Step 6: Get final published URL
Use theneo_publish_project with the project ID
```
### 💡 Real-World Conversation Example
```
You: "Hey, can you help me set up documentation for my API?"
AI: "Of course! Do you have an OpenAPI spec?"
You: "Yes, it's at https://api.mycompany.com/openapi.json"
AI: "Great! What would you like to name the project?"
You: "Call it 'MyCompany API v2' and make it public with AI descriptions"
AI: *[Creates project, waits for AI, shows preview link]*
"Done! Your documentation is live at [URL]. Would you like to make any changes?"
You: "Actually, I need to update the 'MyCompany API v2' project with a new spec"
AI: *[Automatically looks up project by name, imports new spec]*
"Updated! The changes have been merged and published."
```
### 🎯 Using Names Instead of IDs (No More Copy-Paste!)
One of the most powerful features is the ability to reference **both projects and workspaces by name**:
```
# Old way (hard to remember)
"Create project in workspace ws_abc123 and publish project proj_xyz456"
# New way (natural)
"Create a project in my 'Engineering' workspace and publish the 'Payment API' project"
```
The AI will automatically:
1. Resolve workspace name → workspace ID (if needed)
2. Resolve project name → project ID (if needed)
3. Execute the operation
4. Return a friendly message
**This works for:**
- ✅ Workspace references: ID, key (slug), or name
- ✅ Project references: ID or name
- ✅ All project operations: create, import, publish, preview, delete, export
- ✅ Version management: list, create, delete versions
- ✅ AI generation: wait for completion, check status
- ✅ External integrations: list Postman collections, add subscribers
**No more copying and pasting cryptic IDs!**
More examples in [`examples/demo-prompts.md`](./examples/demo-prompts.md).
## Security Best Practices
### ✅ DO
- **Use OS keychain** for API keys on local machines
- **Use environment variables** in CI/CD and containers
- **Enable secret masking** in your CI logs
- **Rotate API keys** regularly and after demos
- **Use profiles** to isolate environments
- **Review `.gitignore`** to exclude secrets
- **Use `.npmignore`** to prevent publishing secrets
### ❌ DON'T
- **Never commit** API keys to git
- **Never log** full configuration objects
- **Never use** API keys in URLs or query parameters
- **Never share** API keys in public channels
- **Avoid** storing keys in project RC files checked into git
### CI/CD Integration
Example GitHub Actions workflow:
```yaml
name: Update API Docs
on:
push:
paths:
- 'openapi.yaml'
jobs:
update-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install Theneo MCP
run: npm install -g theneo-mcp
- name: Update Documentation
env:
THENEO_API_KEY: ${{ secrets.THENEO_API_KEY }}
run: |
# Your automation script here
# Call MCP tools via a script or AI assistant
```
**Security Notes for CI:**
- Store `THENEO_API_KEY` as a GitHub secret
- Use `secrets.` syntax to avoid exposure
- Consider short-lived tokens if Theneo supports OIDC
- Mask secrets in logs: `echo "::add-mask::$THENEO_API_KEY"`
## Development
### Build from Source
```bash
git clone https://github.com/atombreak/theneo-mcp.git
cd theneo-mcp
npm install
npm run build
```
### Development Mode
```bash
npm run dev # Start server with auto-reload
```
### Code Quality
```bash
npm run lint # Run ESLint
npm run format # Format with Prettier
npm run type-check # TypeScript validation
```
### Project Structure
```
theneo-mcp/
├── src/
│ ├── server.ts # MCP server implementation
│ ├── cli.ts # CLI commands
│ ├── config.ts # Configuration schema
│ ├── loadConfig.ts # Multi-source config loader
│ ├── credentials.ts # Keychain management
│ └── utils/
│ └── logger.ts # Structured logging with secret masking
├── examples/ # Sample files and demos
├── dist/ # Compiled output
└── package.json
```
## Troubleshooting
### API Key Not Found
**Problem:** Server exits with "API key not configured"
**Solutions:**
1. Set environment variable: `export THENEO_API_KEY=your_key`
2. Save to keychain: `theneo-mcp creds save --apiKey your_key`
3. Check profile: `theneo-mcp server --profile default`
### Keychain Not Available
**Problem:** "OS keychain is not available"
**Solution:** Use environment variables or config files instead:
```bash
export THENEO_API_KEY=your_key
theneo-mcp server
```
### MCP Server Not Connecting
**Problem:** AI assistant can't find tools
**Solutions:**
1. Restart your AI assistant after config changes
2. Check logs: Look for MCP connection errors
3. Verify command path: Use absolute path to `theneo-mcp`
4. Test manually: Run `theneo-mcp server` to see startup logs
### Import Fails
**Problem:** "Failed to import document"
**Solutions:**
1. Verify file path or URL is accessible
2. Ensure OpenAPI spec is valid JSON/YAML
3. Check project ID is correct
4. Review API key permissions
### AI Generation Timeout
**Problem:** "Generation failed or timed out"
**Solutions:**
1. Increase timeout: `maxWaitTimeMs: 300000` (5 minutes)
2. Check Theneo dashboard for generation status
3. Try again - large specs may take time
## Publishing to npm
### Pre-Publish Checklist
- [ ] Update version in `package.json`
- [ ] Run `npm run type-check`
- [ ] Run `npm run lint`
- [ ] Test build: `npm run build`
- [ ] Verify `.npmignore` excludes secrets
- [ ] Test installation: `npm pack` and install locally
- [ ] Update CHANGELOG.md
### Publish
```bash
npm run prepublishOnly # Runs checks and build
npm publish
```
### What Gets Published
✅ **Included:**
- Compiled JavaScript (`dist/`)
- Package metadata (`package.json`)
- Documentation (`README.md`, `LICENSE`)
❌ **Excluded** (via `.npmignore`):
- TypeScript source (`src/`)
- Test files and coverage (`src/__tests__/`, `coverage/`, `*.test.ts`)
- Environment files (`.env`, `.env.*`)
- Example configurations with potential secrets (`.theneo-mcp.json`, `.theneo-mcp.yaml`)
- Development configs (`tsconfig.json`, `vitest.config.ts`, `eslint.config.js`)
- CI/CD configs (`.github/`, GitHub Actions workflows)
- Docker files (`Dockerfile`, `.dockerignore`)
- IDE settings (`.vscode/`, `.idea/`)
**Security Note:** The `.npmignore` file is configured to exclude all potentially sensitive files. Always review before publishing:
```bash
# Preview what will be published
npm pack --dry-run
# Check for secrets in package
tar -tzf theneo-mcp-*.tgz | grep -E '\.(env|key|pem|crt)'
```
## Testing
This project has comprehensive test coverage with both unit and integration tests.
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
# Open test UI
npm run test:ui
```
## Telemetry
Theneo MCP includes **optional, privacy-first telemetry** to help improve the tool. Telemetry is:
- ✅ **Opt-in** - Disabled by default
- ✅ **Anonymous** - No personal data collected
- ✅ **Local** - Data stored on your machine
- ✅ **Transparent** - View anytime with `theneo-mcp telemetry status`
```bash
# Enable telemetry
theneo-mcp telemetry enable
# View what's collected
theneo-mcp telemetry status
# Disable anytime
theneo-mcp telemetry disable
```
## CI/CD
The project includes comprehensive GitHub Actions workflows:
- **CI**: Runs tests on Node 18, 20, 22 for every push/PR
- **Release**: Automatically publishes to npm and updates Homebrew on version tags
- **Quality**: Weekly security audits and dependency checks
See [.github/workflows/](.github/workflows/) for workflow details.
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. **Write tests for new functionality**
4. Ensure all checks pass: `npm test`
5. Submit a pull request
See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
## License
MIT License - see [LICENSE](LICENSE) file for details
## Links
- **Theneo Platform**: [https://theneo.io](https://theneo.io)
- **Theneo SDK**: [https://www.npmjs.com/package/@theneo/sdk](https://www.npmjs.com/package/@theneo/sdk)
- **Model Context Protocol**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Issues**: [https://github.com/atombreak/theneo-mcp/issues](https://github.com/atombreak/theneo-mcp/issues)
## Support
- **Documentation**: This README and [`examples/demo-prompts.md`](./examples/demo-prompts.md)
- **Issues**: [GitHub Issues](https://github.com/atombreak/theneo-mcp/issues)
- **Theneo Support**: [https://theneo.io/support](https://theneo.io/support)
---
**Made with ❤️ for the AI-powered documentation era**
*Positioning Theneo as the automation backbone for developer documentation*