DTA Knowledge Base MCP Server

MCP (Model Context Protocol) server for TOTVS DTA Knowledge Base integration

This professional MCP server enables AI assistants (Claude, Cursor, etc.) to search and retrieve information from TOTVS DTA Knowledge Bases through the standardized MCP protocol. Install globally and use with a simple CLI.

🚀 Quick Start

Global Installation via NPM (Recommended)

# Install globally from NPM registry
npm install -g dta-kb-mcpserver

# Verify installation
dta-kb-mcp version

Alternative: Installation via Git

# For development or latest version
npm install -g git+https://github.com/[your-username]/dta-kb-mcpserver.git

# Verify installation
dta-kb-mcp version

Environment Configuration

Set up your TOTVS DTA credentials as environment variables:

# Required environment variables
export DTA_PROJECT_KEY="your-project-key"
export DTA_API_KEY="your-api-key"
export DTA_BASE_URL="https://your-instance.totvs.ai"

# Test the configuration
dta-kb-mcp start

# Note: Knowledge base selection is now done dynamically via MCP tools

Local Development

For development and testing:

# Clone and install
git clone https://github.com/[your-username]/dta-kb-mcpserver.git
cd dta-kb-mcpserver
npm install

# Development with hot reload
npm run dev

# Build and test
npm run build
npm test

# Test with coverage
npm test -- --coverage

# Start production server
npm start

🔧 MCP Integration

Claude Desktop

Simplified Global Command Configuration:

Edit your Claude Desktop MCP configuration file:

• macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dta-knowledge-base": {
      "command": "dta-kb-mcp",
      "args": ["start"],
      "env": {
        "DTA_PROJECT_KEY": "your-project-key",
        "DTA_API_KEY": "your-api-key",
        "DTA_BASE_URL": "https://your-instance.totvs.ai"
      }
    }
  }
}

Cursor IDE

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "dta-knowledge-base": {
      "command": "dta-kb-mcp",
      "args": ["start"],
      "env": {
        "DTA_PROJECT_KEY": "your-project-key",
        "DTA_API_KEY": "your-api-key",
        "DTA_BASE_URL": "https://your-instance.totvs.ai"
      }
    }
  }
}

Continue.dev

Add to your Continue configuration:

{
  "mcpServers": [
    {
      "name": "dta-knowledge-base",
      "command": "dta-kb-mcp",
      "args": ["start"],
      "env": {
        "DTA_PROJECT_KEY": "your-project-key",
        "DTA_API_KEY": "your-api-key",
        "DTA_BASE_URL": "https://your-instance.totvs.ai"
      }
    }
  ]
}

💻 CLI Commands

# Show version and information
dta-kb-mcp version

# Show help and usage
dta-kb-mcp help

# Start the MCP server (requires environment variables)
dta-kb-mcp start

🛠️ Available Tools

list_knowledge_bases

List all available TOTVS DTA knowledge bases with their IDs and descriptions.

• Parameters: None
• Returns: List of knowledge bases with IDs, names, and descriptions
• Usage: Call this first to discover which knowledge base to search

search_knowledge_base

Search a specific TOTVS DTA knowledge base for relevant information.

• Parameters:
  • knowledge_base_id (string, required): The ID of the knowledge base (from list_knowledge_bases)
  • query (string, required): Your search query
  • limit (number, optional): Max results (default: 3)
• Returns: AI-generated responses plus source documents from the knowledge base

Typical Workflow

1. AI calls list_knowledge_bases to see available options
2. AI selects the most relevant knowledge base based on descriptions
3. AI calls search_knowledge_base with the chosen KB ID and user's query

⚙️ Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | DTA_PROJECT_KEY | Your DTA project key | Yes | dta-crm-sfa | | DTA_API_KEY | Your DTA API key | Yes | "" | | DTA_BASE_URL | DTA instance URL | Yes | https://totvs.dta.totvs.ai |

Note: KNOWLEDGE_BASE_ID is no longer required. Knowledge bases are now discovered dynamically using the list_knowledge_bases tool.

🔄 Updates

# Update to the latest version from NPM registry
npm update -g dta-kb-mcpserver

# Or install specific version
npm install -g [email protected]

🔧 Troubleshooting

"dta-kb-mcp: command not found"

1. Verify global installation: npm list -g dta-kb-mcpserver
2. Check if npm global bin is in your PATH: npm config get prefix
3. Reinstall: npm install -g dta-kb-mcpserver

"Missing required environment variable"

1. Verify variables are set: echo $DTA_PROJECT_KEY
2. Set variables in your shell profile (.bashrc, .zshrc, etc.):

   export DTA_PROJECT_KEY="your-project-key"
   export DTA_API_KEY="your-api-key"
   export DTA_BASE_URL="https://your-instance.totvs.ai"

3. Reload your shell: source ~/.bashrc (or .zshrc)

"Invalid DTA_BASE_URL format"

• Ensure URL includes protocol: https://your-instance.totvs.ai
• No trailing slash

Claude Desktop not connecting

1. Check Claude Desktop logs in the application
2. Verify MCP configuration file format (valid JSON)
3. Test server manually: dta-kb-mcp start
4. Restart Claude Desktop after configuration changes

🔄 Version History

What's New in v1.0.0

• NPM Registry Distribution: Now installable via npm install -g dta-kb-mcpserver
• Simplified CLI: Global dta-kb-mcp command for easy usage
• Enhanced MCP Integration: Streamlined configuration for all MCP clients
• Optimized Package: Reduced size and faster installation
• Professional Documentation: Comprehensive guides and troubleshooting

📝 License

MIT License

Professional, reliable, and ready to use. 🎯