Theneo MCP Server

Model Context Protocol server for Theneo SDK - The automation backbone for API documentation in the AI era.

<!-- Uncomment when services are live --> <!-- --> <!-- --> <!-- -->

This MCP server exposes Theneo's API documentation platform through the Model Context Protocol, 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)

# Global installation
npm install -g theneo-mcp

# Verify installation
theneo-mcp --version

Homebrew (macOS/Linux)

# Add tap
brew tap theneo/theneo-mcp

# Install
brew install theneo-mcp

# Verify installation
theneo-mcp --version

Docker

# 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 for detailed Docker usage.

Local Development

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/ to get your Theneo API key.

2. Configure Authentication

Option A: OS Keychain (Recommended for local dev)

theneo-mcp creds save --profile default --apiKey YOUR_API_KEY

Option B: Environment Variable

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:

{
  "mcpServers": {
    "theneo": {
      "command": "theneo-mcp",
      "args": ["server"]
    }
  }
}

VS Code Copilot

Add to your VS Code settings.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):

{
  "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:

# .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):

{
  "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:

# 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:

# 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:

{
  "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.

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:

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

git clone https://github.com/atombreak/theneo-mcp.git
cd theneo-mcp
npm install
npm run build

Development Mode

npm run dev  # Start server with auto-reload

Code Quality

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:

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

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:

# 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.

# 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

# 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/ 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 for detailed guidelines.

License

MIT License - see LICENSE file for details

Links

• Theneo Platform: https://theneo.io
• Theneo SDK: https://www.npmjs.com/package/@theneo/sdk
• Model Context Protocol: https://modelcontextprotocol.io
• Issues: https://github.com/atombreak/theneo-mcp/issues

Support

• Documentation: This README and examples/demo-prompts.md
• Issues: GitHub Issues
• Theneo Support: https://theneo.io/support

---

Made with ❤️ for the AI-powered documentation era

Positioning Theneo as the automation backbone for developer documentation