# Content Manager MCP Server

A comprehensive TypeScript-based Model Context Protocol (MCP) server for content management, including Markdown processing, document generation, and intelligent note searching.

## 🚀 Features

### 📝 Markdown Processing
- **Render Markdown to HTML** with table of contents generation
- **Extract headings** and create structured navigation
- **Parse frontmatter** from Markdown files
- **HTML sanitization** for safe content processing

### 🔍 Intelligent Search
- **Fuzzy search** through notes using Fuse.js
- **Exact text matching** with context highlighting  
- **Tag-based filtering** using frontmatter metadata
- **Date range queries** for time-based content discovery

### 📊 Content Analysis
- **Directory statistics** showing file counts, sizes, and types
- **File discovery** with customizable extension filtering
- **Content preview** with metadata extraction

## 🛠 Tech Stack

- **TypeScript** - Type-safe development with latest ES2023 features
- **Zod** - Runtime schema validation and type inference
- **tsup** - Fast TypeScript bundler with ESM support
- **pnpm** - Efficient package management
- **Fuse.js** - Fuzzy search functionality
- **marked** - Markdown parsing and rendering

## 📦 Installation

### Option 1: NPM Package (Recommended)
```bash
# Install globally
npm install -g content-manager-mcp

# Or use directly with npx
npx -y content-manager-mcp
```

### Option 2: From Source
#### Prerequisites
- Node.js >= 20.0.0
- pnpm >= 9.0.0

#### Setup
```bash
# Clone and install dependencies
git clone <repository-url>
cd content-manager-mcp
pnpm install

# Build the project
pnpm build

# Run in development mode
pnpm dev
```

## 🔧 Usage

### As MCP Server
The server runs via stdio and implements the MCP protocol:

#### Using NPM Package
```bash
# If installed globally
content-manager-mcp

# Using npx (no installation required)
npx -y content-manager-mcp
```

#### Using Source Build
```bash
node dist/index.js
```

### MCP Client Configuration

#### Claude Desktop
Add to your Claude Desktop configuration:
```json
{
  "mcpServers": {
    "content-manager": {
      "command": "npx",
      "args": ["-y", "content-manager-mcp"]
    }
  }
}
```

#### Cherry Studio
Configure MCP server:
- **Command**: `npx`
- **Arguments**: `["-y", "content-manager-mcp"]`

#### Codex
Add to your Codex MCP servers configuration:
```json
{
  "mcpServers": {
    "content-manager": {
      "command": "npx",
      "args": ["-y", "content-manager-mcp"]
    }
  }
}
```

#### Claude Code
Add MCP server using Claude Code CLI:
```bash
# Add content-manager-mcp server to Claude Code
claude mcp add content-manager -- npx -y content-manager-mcp

# Or if you prefer to install globally first
npm install -g content-manager-mcp
claude mcp add content-manager -- content-manager-mcp
```

#### VS Code
Install the MCP extension and configure:
1. Install the MCP extension from VS Code marketplace
2. Add to your VS Code settings (`settings.json`):
```json
{
  "mcp.servers": {
    "content-manager": {
      "command": "npx",
      "args": ["-y", "content-manager-mcp"]
    }
  }
}
```

#### Cursor
Configure MCP server in Cursor settings:
1. Open Cursor settings
2. Navigate to MCP configuration
3. Add new server:
   - **Name**: `content-manager`
   - **Command**: `npx`
   - **Arguments**: `["-y", "content-manager-mcp"]`

Or add to Cursor's `settings.json`:
```json
{
  "mcp.servers": {
    "content-manager": {
      "command": "npx",
      "args": ["-y", "content-manager-mcp"]
    }
  }
}
```

### Available Tools

#### `render_markdown`
Converts Markdown content to HTML with optional features:
```typescript
{
  content: string,           // Markdown content to render
  generateToc?: boolean,     // Generate table of contents (default: true)
  sanitizeHtml?: boolean,    // Sanitize output HTML (default: true)
  enableCodeHighlight?: boolean // Enable syntax highlighting (default: true)
}
```

#### `search_notes`
Intelligent search through content files:
```typescript
{
  query: string,             // Search query
  directory?: string,        // Directory to search (default: cwd)
  includeContent?: boolean,  // Include file content in results (default: true)
  maxResults?: number,       // Maximum results to return (default: 10)
  fuzzy?: boolean           // Use fuzzy search (default: true)
}
```

#### `search_by_tags`
Find files by frontmatter tags:
```typescript
{
  tags: string[],           // Array of tags to search for
  directory?: string        // Directory to search (default: cwd)
}
```

#### `search_by_date_range`
Find files by modification date:
```typescript
{
  startDate: string,        // ISO date string (YYYY-MM-DD)
  endDate: string,          // ISO date string (YYYY-MM-DD)
  directory?: string        // Directory to search (default: cwd)
}
```

#### `generate_table_of_contents`
Extract and format headings as a table of contents:
```typescript
{
  content: string           // Markdown content to analyze
}
```

#### `extract_headings`
Get structured heading information:
```typescript
{
  content: string           // Markdown content to analyze
}
```

#### `extract_frontmatter`
Parse YAML frontmatter from Markdown:
```typescript
{
  content: string           // Markdown content with frontmatter
}
```

#### `get_directory_stats`
Analyze directory content statistics:
```typescript
{
  directory?: string        // Directory to analyze (default: cwd)
}
```

#### `find_content_files`
Discover files with specific extensions:
```typescript
{
  directory?: string,           // Directory to search (default: cwd)
  extensions?: string[]         // File extensions (default: ['.md', '.markdown', '.txt', '.mdx'])
}
```

#### `read_content_file`
Read and parse a single content file:
```typescript
{
  filePath: string             // Path to file to read
}
```

## 🧪 Development

### Scripts
- `pnpm dev` - Development mode with watch
- `pnpm build` - Build for production
- `pnpm start` - Run built server
- `pnpm lint` - Check code style
- `pnpm lint:fix` - Fix code style issues
- `pnpm type-check` - TypeScript type checking
- `pnpm clean` - Clean build artifacts

### Type Safety
This project leverages Zod for runtime validation combined with TypeScript for compile-time safety. All tool arguments are validated at runtime, ensuring robust error handling and type safety.

### Error Handling
- Comprehensive error catching and reporting
- Zod validation errors with descriptive messages
- File system error handling
- Graceful degradation for malformed content

## 📝 Example Usage

### Frontmatter Format
The server recognizes YAML frontmatter in Markdown files:

```markdown
---
title: My Document
tags: [typescript, mcp, documentation]
author: Your Name
date: 2024-01-15
---

# Document Content

Your markdown content here...
```

### Search Examples
- **Fuzzy search**: `query: "typescript mcp"` (finds related content)
- **Exact search**: `query: "exact phrase", fuzzy: false`
- **Tag search**: `tags: ["typescript", "documentation"]`
- **Date search**: `startDate: "2024-01-01", endDate: "2024-12-31"`

## 📤 Publishing

This package is published to NPM as `@yugangcao/content-manager-mcp`. To publish a new version:

```bash
# Build the project
pnpm build

# Update version (patch/minor/major)
npm version patch

# Publish to NPM
npm publish
```

For detailed publishing instructions, see [PUBLISH_TO_NPM.md](./PUBLISH_TO_NPM.md).

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make changes and add tests
4. Ensure types are correct: `pnpm type-check`
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details.

---

**Built with ❤️ using TypeScript, Zod, and the latest modern tooling for robust content management.**