README.md•14.3 kB
# @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](./ARCHITECTURE.md) for detailed architecture documentation.
## Installation
```bash
npm install
```
## Building
```bash
# Build all packages
npm run build
# Clean build artifacts
npm run clean
```
## Usage
Install the packages you need in your project:
```bash
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:
```typescript
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:
```json
{
"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:
```json
[
{
"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 parameters
- `mysql_execute` - Execute INSERT/UPDATE/DELETE/DDL (WRITEONLY or FULL mode)
- `mysql_list_databases` - List all databases
- `mysql_list_tables` - List tables in database
- `mysql_describe_table` - Get table structure
- `mysql_list_indexes` - List table indexes
- `mysql_list_constraints` - List table constraints
- `mysql_explain_query` - Query execution plan
- `mysql_processlist` - View running queries
- `mysql_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 views
- `mysql_list_procedures` - List stored procedures
- `mysql_list_functions` - List stored functions
- `mysql_list_triggers` - List triggers
- And more...
**Dependencies:** `mysql2`
**Modes:** READONLY, WRITEONLY, FULL
**See:** [packages/mysql/README.md](./packages/mysql/README.md)
### SQL Server Plugin (`@nam088/mcp-sql-server`)
Microsoft SQL Server plugin with comprehensive tools.
**Tools:**
- `sqlserver_query` - Execute SELECT queries
- `sqlserver_execute` - Execute INSERT/UPDATE/DELETE/DDL (FULL mode)
- `sqlserver_list_databases` - List all databases
- `sqlserver_list_tables` - List tables in schema
- `sqlserver_describe_table` - Get table structure
- `sqlserver_list_schemas` - List all schemas
- `sqlserver_list_indexes` - List table indexes
- `sqlserver_list_constraints` - List table constraints
- `sqlserver_explain_query` - Query execution plan
- `sqlserver_active_sessions` - View active sessions
- `sqlserver_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](./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, projection
- `mongodb_count` - Count documents
- `mongodb_aggregate` - Run aggregation pipeline
- `mongodb_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 databases
- `mongodb_list_collections` - List collections in database
- `mongodb_collection_stats` - Get collection statistics
- `mongodb_list_indexes` - List collection indexes
- `mongodb_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](./packages/mongodb/README.md)
### Redis Plugin (`@nam088/mcp-redis`)
Redis plugin with support for all data types.
**Tools:**
- `redis_get` - Get value by key
- `redis_set` - Set value with optional TTL
- `redis_del` - Delete key
- `redis_keys` - Find keys by pattern
- `redis_info` - Get server information
- And more... (hash, list, set, sorted set operations)
**Dependencies:** `redis`
**See:** [packages/redis/README.md](./packages/redis/README.md)
### PostgreSQL Plugin (`@nam088/mcp-postgres`)
PostgreSQL plugin with comprehensive SQL support.
**Tools:**
- `postgres_query` - Execute SELECT queries
- `postgres_execute` - Execute INSERT/UPDATE/DELETE/DDL (FULL mode)
- `postgres_list_tables` - List all tables in schema
- `postgres_describe_table` - Get table structure
- `postgres_list_schemas` - List all schemas
- `postgres_list_indexes` - List table indexes
- `postgres_database_info` - Get database information
**Dependencies:** `pg`
**See:** [packages/postgres/README.md](./packages/postgres/README.md)
## Creating Custom Plugins
### 1. Create Plugin Package
```bash
mkdir -p packages/mydb/src
cd packages/mydb
npm init -y
```
### 2. Setup package.json
```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
```json
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
```
### 4. Implement Plugin
```typescript
// 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
```bash
# Build your plugin
cd packages/mydb
npm run build
# Use it in your server
npm install @nam088/mcp-mydb
```
## Development
```bash
# 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
1. **Plugin Independence**: Each plugin has its own dependencies
- MySQL: `mysql2`
- SQL Server: `mssql`
- MongoDB: `mongodb`
- Redis: `redis`
- PostgreSQL: `pg`
2. **Selective Installation**: Install only the plugins you need
3. **No Dependency Conflicts**: Plugins don't interfere with each other
4. **Easy Publishing**: Each plugin can be published to npm independently
5. **Flexible Loading**: Choose static imports or dynamic loading
6. **Type Safety**: Full TypeScript support across all packages
7. **Mode Control**: READONLY, WRITEONLY (MySQL), or FULL modes for security
8. **Standalone Servers**: Each plugin can run as a standalone MCP server
## License
MIT
## Author
nam088