Synergy/DE MCP Server
A read-only Model Context Protocol (MCP) server that exposes Synergy/DE documentation as tools and resources, making it easy to search, retrieve, and browse documentation topics from Cursor and other MCP clients.
Features
- Full-text search across Synergy/DE documentation with relevance scoring
- Topic retrieval with chunked content optimized for LLM consumption
- Related topics navigation (previous, next, parent, and related links)
- Section browsing to discover topics by category
- Version support for different Synergy/DE documentation versions
- Intelligent caching to minimize network requests and improve performance
- Online and local documentation support (hybrid mode available)
- MCP Resources for direct topic and section access in Cursor
Prerequisites
- Node.js 18.0.0 or higher (provides built-in
fetchAPI for HTTP requests) - npm or pnpm package manager
- Cursor (for MCP integration) or another MCP-compatible client
Installation
-
Clone this repository:
git clone https://github.com/h0ck3ystyx/synergyde-mcp.git cd synergyde-mcp -
Install dependencies:
npm install # or pnpm install -
Build the project:
npm run build -
Configure environment variables (optional):
cp .env.example .env # Edit .env with your preferences
Configuration
The server can be configured via environment variables. All variables are optional and have sensible defaults.
Environment Variables
| Variable | Description | Default | Required |
|---|---|---|---|
SYNERGYDE_DOC_BASE_URL | Base URL for online documentation | https://www.synergex.com/docs/ | No |
SYNERGYDE_DOC_DEFAULT_VERSION | Default documentation version to use | "latest" | No |
SYNERGYDE_LOCAL_DOC_PATH | Path to local documentation directory | (none) | No |
SYNERGYDE_CACHE_DIR | Directory for caching parsed topics | ./cache | No |
LOG_LEVEL | Logging level: debug, info, warn, or error | info | No |
Configuration Details
-
SYNERGYDE_DOC_BASE_URL: The base URL for the Synergy/DE documentation site. Should end with a trailing slash (automatically added if missing). -
SYNERGYDE_DOC_DEFAULT_VERSION: The default version to use when no version is specified in tool calls. Common values:"latest","v111","v112", etc. -
SYNERGYDE_LOCAL_DOC_PATH: If provided, enables local documentation support. The path must be readable and point to a directory containing local documentation files. When set, the server operates in "hybrid" mode, preferring local docs but falling back to online docs if a topic isn't found locally. -
SYNERGYDE_CACHE_DIR: Directory where parsed topics are cached on disk. The directory will be created automatically if it doesn't exist. Cached topics are stored as JSON files keyed by version and topic ID. -
LOG_LEVEL: Controls the verbosity of logging. Usedebugfor detailed information during development,infofor normal operation,warnfor warnings only, orerrorfor errors only.
Example .env File
# Use online documentation with latest version
SYNERGYDE_DOC_BASE_URL=https://www.synergex.com/docs/
SYNERGYDE_DOC_DEFAULT_VERSION=latest
# Cache directory (relative to project root)
SYNERGYDE_CACHE_DIR=./cache
# Logging level
LOG_LEVEL=info
Usage
Running the Server
The server uses stdio transport and is designed to be launched by MCP clients:
npm start
The server will:
- Initialize configuration
- Connect to stdio transport
- Wait for MCP requests from clients
Note: The server is intended to be run by MCP clients (like Cursor), not directly. Running it manually will cause it to wait for input on stdin.
Cursor MCP Configuration
Add the server to your Cursor MCP configuration. The configuration file location depends on your setup:
- Global config:
~/.cursor/mcp.json(macOS/Linux) or%APPDATA%\Cursor\mcp.json(Windows) - Project config:
.cursor/mcp.jsonin your project root
Basic Configuration
{
"mcpServers": {
"synergyde-docs": {
"command": "node",
"args": ["/absolute/path/to/synergyde-mcp/dist/server.js"],
"env": {
"SYNERGYDE_DOC_DEFAULT_VERSION": "latest"
}
}
}
}
Advanced Configuration with Local Docs
{
"mcpServers": {
"synergyde-docs": {
"command": "node",
"args": ["/absolute/path/to/synergyde-mcp/dist/server.js"],
"env": {
"SYNERGYDE_DOC_BASE_URL": "https://www.synergex.com/docs/",
"SYNERGYDE_DOC_DEFAULT_VERSION": "latest",
"SYNERGYDE_LOCAL_DOC_PATH": "/path/to/local/docs",
"SYNERGYDE_CACHE_DIR": "/path/to/cache",
"LOG_LEVEL": "info"
}
}
}
}
Important: Use absolute paths for the server executable and any file paths in the configuration.
Available Tools
The server exposes the following MCP tools:
search_docs
Search documentation topics using full-text search.
Parameters:
query(required): Search query stringversion(optional): Documentation version (defaults to configured default)section(optional): Filter by section namelimit(optional): Maximum number of results (default: 10)
Returns: Array of search results with relevance scores
get_topic
Fetch a documentation topic by ID or URL.
Parameters:
topic_id(optional): Topic ID (e.g.,"Language/variables.htm")url(optional): Full URL to the topic pageversion(optional): Documentation versionmax_chunks(optional): Maximum number of chunks to return (default: 3, 0 = no limit)
Returns: Topic object with chunked content
get_related_topics
Get related topics (previous, next, parent, related links) for a given topic.
Parameters:
topic_id(required): Topic IDversion(optional): Documentation version
Returns: RelatedTopics object with navigation links
list_section_topics
List all topics in a documentation section.
Parameters:
section(required): Section name (e.g.,"Language","Reference")version(optional): Documentation versionlimit(optional): Maximum number of topics (default: 50)
Returns: Array of topic summaries
describe_docs
Get metadata about available documentation.
Parameters: None
Returns: DocMetadata with versions, sections, and source type
Available Resources
The server exposes the following MCP resources:
Topic Resource
URI: synergyde:topic/{topic_id} or synergyde:topic/{version}/{topic_id}
Returns plain text content of a documentation topic with metadata. Content is limited to ~8k tokens to fit within LLM context windows.
Examples:
synergyde:topic/Language/variables.htmsynergyde:topic/latest/Language/variables.htmsynergyde:topic//Language/variables.htm(explicit no version)
Section Resource
URI: synergyde:section/{version}/{section}
Returns a plain text index of topics in a section with titles, IDs, URLs, and summaries. Content is limited to ~8k tokens.
Examples:
synergyde:section/latest/Languagesynergyde:section/v111/Reference
Error Handling
All tools and resources return structured error payloads with the following format:
{
code: string; // Error code (e.g., "TOPIC_NOT_FOUND", "NETWORK_ERROR")
message: string; // Human-readable error message
details?: { // Additional context
topic_id?: string;
version?: string;
// ... other fields
};
retryable?: boolean; // Whether the error is retryable
}
Common Error Codes
INVALID_INPUT: Invalid input parameters (not retryable)TOPIC_NOT_FOUND: Requested topic doesn't exist (not retryable)SECTION_NOT_FOUND: Requested section doesn't exist (not retryable)VERSION_NOT_FOUND: Requested version doesn't exist (not retryable)NETWORK_ERROR: Network/HTTP error (usually retryable)CACHE_ERROR: Cache operation failed (usually retryable)PROVIDER_ERROR: Provider-specific error (not retryable)INTERNAL_ERROR: Unexpected internal error (not retryable)
Troubleshooting
Server won't start:
- Verify Node.js version:
node --version(must be 18+) - Check dependencies:
npm install - Verify TypeScript compilation:
npm run build - Check logs for specific error messages
Tools return errors:
- Verify network connectivity (for online provider)
- Check that topic IDs are correct
- Verify the documentation version exists
- Check server logs for detailed error information
Cache not working:
- Verify
SYNERGYDE_CACHE_DIRis writable - Check file permissions on cache directory
- Look for cache errors in server logs
Cursor integration issues:
- Verify MCP configuration file syntax (valid JSON)
- Use absolute paths for server executable
- Check Cursor's MCP server status/logs
- Restart Cursor after configuration changes
- Verify environment variables are set correctly
Development
Project Structure
src/
├── server.ts # Main MCP server entry point
├── types.ts # TypeScript type definitions
├── config.ts # Configuration and environment variables
├── tools/ # MCP tool implementations
│ ├── search-docs.ts
│ ├── get-topic.ts
│ ├── get-related-topics.ts
│ ├── list-section-topics.ts
│ └── describe-docs.ts
├── resources/ # MCP resource handlers
│ ├── topic-resource.ts
│ └── section-resource.ts
└── lib/
├── providers/ # Documentation providers (online/local/hybrid)
├── parser/ # HTML parsing and chunking
├── search/ # Search index implementation
├── cache/ # Disk caching layer
└── utils/ # Utilities (logger, errors)
Development Commands
# Build TypeScript
npm run build
# Watch mode for development
npm run dev
# Run linter
npm run lint
# Fix linting issues automatically
npm run lint:fix
# Type checking (no emit)
npm run typecheck
# Run tests
npm test
# Run tests with coverage
npm test -- --coverage
# Run tests in watch mode
npm run test:watch
Testing
The project uses Vitest for testing with comprehensive coverage:
- Unit tests: Test individual modules in isolation
- Integration tests: Test tool handlers and workflows
- End-to-end tests: Test complete flows (search → get_topic → get_related)
See MANUAL_TESTING.md for manual testing procedures.
Code Quality
- TypeScript: Strict type checking enabled
- ESLint: Code linting with TypeScript support
- Test Coverage: ≥80% statement coverage required
- Error Handling: Structured error payloads, no unhandled exceptions
Architecture
Design Principles
- Modularity: Small, composable modules with clear responsibilities
- Type Safety: Strong TypeScript typing throughout
- Error Handling: Structured errors, no unhandled exceptions
- Caching: Aggressive caching to minimize network calls
- Read-Only: No write operations, respect remote resources
- LLM-Friendly: Chunked, structured content optimized for AI consumption
- Deterministic: Idempotent operations, stable results
Key Components
- Providers: Fetch documentation from online or local sources
- Parser: Extract and structure content from HTML
- Chunker: Split content into LLM-friendly chunks
- Cache: Disk-based caching for parsed topics
- Search Index: In-memory full-text search with relevance scoring
- MCP Server: Expose tools and resources via Model Context Protocol
License
MIT
Contributing
Contributions are welcome! Please ensure:
- All tests pass:
npm test - Code is properly typed (no
anytypes) - Coverage remains ≥80%
- Linting passes:
npm run lint