@nam088/mcp-server
A professional MCP (Model Context Protocol) server implementation with a plugin-based architecture.
Features
- Plugin-Based Architecture: Modular design with independent plugins
- Workspace Structure: Each plugin is a separate npm package with its own dependencies
- Dynamic Loading: Load plugins from configuration or environment variables
- Type-Safe: Full TypeScript support
- Extensible: Easy to create custom plugins
Architecture
This project uses a monorepo workspace structure where:
- Core System (
@nam088/mcp-core): Plugin interfaces and registry - Plugins (e.g.,
@nam088/mcp-redis): Independent packages with their own dependencies - Main Server: Loads and orchestrates plugins
See ARCHITECTURE.md for detailed architecture documentation.
Installation
npm install
Building
# Build all packages
npm run build
# Clean build artifacts
npm run clean
Usage
Install the packages you need in your project:
npm install @nam088/mcp-core @nam088/mcp-mysql @nam088/mcp-sql-server @nam088/mcp-mongodb @nam088/mcp-postgres @nam088/mcp-redis
Create your MCP server:
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { PluginRegistry } from '@nam088/mcp-core';
import { MysqlPlugin } from '@nam088/mcp-mysql';
import { SqlServerPlugin } from '@nam088/mcp-sql-server';
import { MongoDBPlugin } from '@nam088/mcp-mongodb';
import { PostgresPlugin } from '@nam088/mcp-postgres';
import { RedisPlugin } from '@nam088/mcp-redis';
const server = new Server(
{ name: 'my-mcp-server', version: '1.0.0' },
{ capabilities: { tools: {} } }
);
const registry = new PluginRegistry(server);
// Register plugins with connection strings (recommended)
await registry.registerPlugin(MongoDBPlugin, {
uri: process.env.MONGODB_URI || 'mongodb://localhost:27017',
mode: 'READONLY',
});
await registry.registerPlugin(PostgresPlugin, {
url: process.env.POSTGRES_URL || 'postgresql://postgres:password@localhost:5432/mydb',
mode: 'READONLY',
});
await registry.registerPlugin(RedisPlugin, {
url: process.env.REDIS_URL || 'redis://localhost:6379',
});
// MySQL (using individual config - connection string not yet supported)
await registry.registerPlugin(MysqlPlugin, {
host: process.env.MYSQL_HOST || 'localhost',
port: parseInt(process.env.MYSQL_PORT || '3306'),
user: process.env.MYSQL_USER || 'root',
password: process.env.MYSQL_PASSWORD,
database: process.env.MYSQL_DATABASE,
mode: 'READONLY',
});
// SQL Server (using individual config)
await registry.registerPlugin(SqlServerPlugin, {
server: process.env.MSSQL_HOST || 'localhost',
port: parseInt(process.env.MSSQL_PORT || '1433'),
user: process.env.MSSQL_USER || 'sa',
password: process.env.MSSQL_PASSWORD,
database: process.env.MSSQL_DATABASE,
mode: 'READONLY',
});
// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
Configuration Examples
MCP Server Configuration (for Cursor/Claude Desktop)
Add to your ~/.cursor/mcp.json or Claude Desktop config:
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": ["-y", "@nam088/mcp-mongodb"],
"env": {
"MONGODB_URI": "mongodb://admin:admin@localhost:27017/db_name?authMechanism=SCRAM-SHA-256",
"MONGODB_DATABASE": "mydb",
"MONGODB_MODE": "READONLY"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@nam088/mcp-postgres"],
"env": {
"POSTGRES_URL": "postgresql://postgres:password@localhost:5432/mydb",
"POSTGRES_MODE": "READONLY"
}
},
"redis": {
"command": "npx",
"args": ["-y", "@nam088/mcp-redis"],
"env": {
"REDIS_URL": "redis://localhost:6379"
}
},
"mysql": {
"command": "npx",
"args": ["-y", "@nam088/mcp-mysql"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "mydb",
"MYSQL_MODE": "READONLY"
}
},
"sql-server": {
"command": "npx",
"args": ["-y", "@nam088/mcp-sql-server"],
"env": {
"MSSQL_HOST": "localhost",
"MSSQL_PORT": "1433",
"MSSQL_USER": "sa",
"MSSQL_PASSWORD": "your_password",
"MSSQL_DATABASE": "mydb",
"MSSQL_MODE": "READONLY"
}
}
}
}
Plugin Configuration (for Dynamic Loading)
Create a plugins.config.json file for dynamic plugin loading:
[
{
"package": "@nam088/mcp-mongodb",
"export": "MongoDBPlugin",
"enabled": true,
"config": {
"uri": "mongodb://admin:admin@localhost:27017/db_name",
"mode": "READONLY"
}
},
{
"package": "@nam088/mcp-postgres",
"export": "PostgresPlugin",
"enabled": true,
"config": {
"url": "postgresql://postgres:password@localhost:5432/mydb",
"mode": "READONLY"
}
},
{
"package": "@nam088/mcp-redis",
"export": "RedisPlugin",
"enabled": true,
"config": {
"url": "redis://localhost:6379"
}
},
{
"package": "@nam088/mcp-mysql",
"export": "MysqlPlugin",
"enabled": true,
"config": {
"host": "localhost",
"port": 3306,
"user": "root",
"password": "your_password",
"database": "mydb",
"mode": "READONLY"
}
},
{
"package": "@nam088/mcp-sql-server",
"export": "SqlServerPlugin",
"enabled": true,
"config": {
"server": "localhost",
"port": 1433,
"user": "sa",
"password": "your_password",
"database": "mydb",
"mode": "READONLY"
}
}
]
Available Plugins
MySQL Plugin (@nam088/mcp-mysql)
Comprehensive MySQL/MariaDB plugin with 20+ tools.
Tools:
mysql_query- Execute SELECT queries with parametersmysql_execute- Execute INSERT/UPDATE/DELETE/DDL (WRITEONLY or FULL mode)mysql_list_databases- List all databasesmysql_list_tables- List tables in databasemysql_describe_table- Get table structuremysql_list_indexes- List table indexesmysql_list_constraints- List table constraintsmysql_explain_query- Query execution planmysql_processlist- View running queriesmysql_kill_query- Kill running query (WRITEONLY or FULL mode)mysql_optimize_table- Optimize tables (WRITEONLY or FULL mode)mysql_analyze_table- Analyze tables (WRITEONLY or FULL mode)mysql_list_views- List viewsmysql_list_procedures- List stored proceduresmysql_list_functions- List stored functionsmysql_list_triggers- List triggers- And more...
Dependencies: mysql2
Modes: READONLY, WRITEONLY, FULL
See: packages/mysql/README.md
SQL Server Plugin (@nam088/mcp-sql-server)
Microsoft SQL Server plugin with comprehensive tools.
Tools:
sqlserver_query- Execute SELECT queriessqlserver_execute- Execute INSERT/UPDATE/DELETE/DDL (FULL mode)sqlserver_list_databases- List all databasessqlserver_list_tables- List tables in schemasqlserver_describe_table- Get table structuresqlserver_list_schemas- List all schemassqlserver_list_indexes- List table indexessqlserver_list_constraints- List table constraintssqlserver_explain_query- Query execution plansqlserver_active_sessions- View active sessionssqlserver_kill_session- Kill session (FULL mode)sqlserver_rebuild_index- Rebuild indexes (FULL mode)sqlserver_update_statistics- Update statistics (FULL mode)- And more...
Dependencies: mssql
Modes: READONLY, FULL
See: packages/sql-server/README.md
MongoDB Plugin (@nam088/mcp-mongodb)
MongoDB plugin with CRUD and aggregation support.
Tools:
mongodb_find- Find documents with filtering, sorting, projectionmongodb_count- Count documentsmongodb_aggregate- Run aggregation pipelinemongodb_insert_one- Insert single document (FULL mode)mongodb_insert_many- Insert multiple documents (FULL mode)mongodb_update_one- Update single document (FULL mode)mongodb_update_many- Update multiple documents (FULL mode)mongodb_delete_one- Delete single document (FULL mode)mongodb_delete_many- Delete multiple documents (FULL mode)mongodb_list_databases- List all databasesmongodb_list_collections- List collections in databasemongodb_collection_stats- Get collection statisticsmongodb_list_indexes- List collection indexesmongodb_create_index- Create index (FULL mode)mongodb_drop_index- Drop index (FULL mode)- And more...
Dependencies: mongodb
Modes: READONLY, FULL
See: packages/mongodb/README.md
Redis Plugin (@nam088/mcp-redis)
Redis plugin with support for all data types.
Tools:
redis_get- Get value by keyredis_set- Set value with optional TTLredis_del- Delete keyredis_keys- Find keys by patternredis_info- Get server information- And more... (hash, list, set, sorted set operations)
Dependencies: redis
See: packages/redis/README.md
PostgreSQL Plugin (@nam088/mcp-postgres)
PostgreSQL plugin with comprehensive SQL support.
Tools:
postgres_query- Execute SELECT queriespostgres_execute- Execute INSERT/UPDATE/DELETE/DDL (FULL mode)postgres_list_tables- List all tables in schemapostgres_describe_table- Get table structurepostgres_list_schemas- List all schemaspostgres_list_indexes- List table indexespostgres_database_info- Get database information
Dependencies: pg
See: packages/postgres/README.md
Creating Custom Plugins
1. Create Plugin Package
mkdir -p packages/mydb/src
cd packages/mydb
npm init -y
2. Setup package.json
{
"name": "@nam088/mcp-mydb",
"version": "0.1.0",
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"scripts": {
"build": "tsc",
"clean": "rm -rf dist",
"type-check": "tsc --noEmit"
},
"peerDependencies": {
"@modelcontextprotocol/sdk": "^1.21.1",
"@nam088/mcp-core": "^0.1.0"
},
"dependencies": {
"mydb-client": "^1.0.0"
},
"devDependencies": {
"@types/node": "^22.10.2",
"typescript": "^5.7.2"
}
}
3. Create tsconfig.json
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
4. Implement Plugin
// packages/mydb/src/index.ts
import { PluginBase, PluginConfig, PluginContext } from '@nam088/mcp-core';
import { z } from 'zod';
export class MyDBPlugin extends PluginBase {
readonly metadata: PluginConfig = {
name: 'mydb',
version: '0.1.0',
description: 'MyDB plugin for MCP',
};
async initialize(context: PluginContext): Promise<void> {
await super.initialize(context);
// Initialize your DB connection
}
register(context: PluginContext): void {
const { server } = context;
server.registerTool('mydb_query', {
description: 'Query MyDB',
inputSchema: {
query: z.string().describe('SQL query'),
}
}, async ({ query }) => {
// Implement your tool
return {
content: [{ type: 'text', text: 'Result' }]
};
});
}
async cleanup(): Promise<void> {
await super.cleanup();
// Cleanup resources
}
}
5. Build and Use
# Build your plugin
cd packages/mydb
npm run build
# Use it in your server
npm install @nam088/mcp-mydb
Development
# Build all packages
npm run build
# Type checking
npm run type-check
# Linting
npm run lint
npm run lint:fix
# Formatting
npm run format
npm run format:check
# Clean build artifacts
npm run clean
Project Structure
mcp-server/
├── packages/
│ ├── core/ # @nam088/mcp-core
│ │ ├── src/
│ │ ├── package.json
│ │ └── tsconfig.json
│ ├── mysql/ # @nam088/mcp-mysql
│ │ ├── src/
│ │ ├── bin/
│ │ ├── package.json
│ │ └── tsconfig.json
│ ├── sql-server/ # @nam088/mcp-sql-server
│ │ ├── src/
│ │ ├── bin/
│ │ ├── package.json
│ │ └── tsconfig.json
│ ├── mongodb/ # @nam088/mcp-mongodb
│ │ ├── src/
│ │ ├── bin/
│ │ ├── package.json
│ │ └── tsconfig.json
│ ├── redis/ # @nam088/mcp-redis
│ │ ├── src/
│ │ ├── bin/
│ │ ├── package.json
│ │ └── tsconfig.json
│ └── postgres/ # @nam088/mcp-postgres
│ ├── src/
│ ├── bin/
│ ├── package.json
│ └── tsconfig.json
├── package.json # Root package with workspaces
├── tsconfig.json # Shared TypeScript config
├── ARCHITECTURE.md # Architecture documentation
└── QUICK_START.md # Vietnamese quick start guide
Benefits of This Architecture
- Plugin Independence: Each plugin has its own dependencies
- MySQL:
mysql2 - SQL Server:
mssql - MongoDB:
mongodb - Redis:
redis - PostgreSQL:
pg
- MySQL:
- Selective Installation: Install only the plugins you need
- No Dependency Conflicts: Plugins don't interfere with each other
- Easy Publishing: Each plugin can be published to npm independently
- Flexible Loading: Choose static imports or dynamic loading
- Type Safety: Full TypeScript support across all packages
- Mode Control: READONLY, WRITEONLY (MySQL), or FULL modes for security
- Standalone Servers: Each plugin can run as a standalone MCP server
License
MIT
Author
nam088