tiwater/supen-edit

Supen Edit

A Model Context Protocol (MCP) server with HTTP API and interactive playground for testing document management tools.

Features

🎯 Document Editor

• Word-Style Formatting: Bold, italic, underline, headings
• Structure Tools: Headers (H1-H3), bullet lists, numbered lists
• Real-time Statistics: Word count, character count, paragraph count
• Document Analysis: Structure parsing and content insights
• Version History: Track document changes over time

🤖 MCP Server Integration

• Built-in MCP API: HTTP endpoints with streaming support
• Document Management: Create, read, update, delete documents
• Document Structure Parsing: Extract sections, paragraphs, tables
• Search & Analysis: Full-text search within documents
• Version Control: Track document changes and history
• Comments System: Add and manage document comments
• DOCX Support: Native Microsoft Word document processing

🌐 Web Interface

• Modern Design: Responsive design with dark/light mode support
• MCP Playground: Two modes for testing MCP functionality:
  • Tool Call Mode: Direct tool testing with examples
  • Chat Mode: Natural language interface powered by DeepSeek
• API Documentation: Interactive documentation with examples
• Document Viewer: Integrated viewer with iframe embedding support
• Real-time Updates: Live document preview and updates

Quick Start

1. Install Dependencies

pnpm install

2. Configure Environment Variables (Optional)

For chat mode functionality, create a .env.local file:

cp .env.example .env.local

Then add your DeepSeek API key:

DEEPSEEK_API_KEY=your_api_key_here

3. Run Development Server

pnpm dev

Visit http://localhost:3301 to access the document editor.

4. Generate API Documentation

pnpm generate:docs

Then visit http://localhost:3301/docs to view the interactive API documentation.

MCP API Usage

The MCP server is available through HTTP endpoints:

Initialize Connection

curl -X POST http://localhost:3301/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

List Available Tools

curl -X POST http://localhost:3301/api/mcp/tools/list \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call a Tool

curl -X POST http://localhost:3301/api/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_document",
      "arguments": {
        "title": "My Document",
        "content": "Hello World"
      }
    }
  }'

Streaming API (Server-Sent Events)

const eventSource = new EventSource('/api/mcp/stream');
eventSource.onmessage = (event) => {
  console.log('Received:', JSON.parse(event.data));
};

Available MCP Tools

Project Structure

supen-edit/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   └── mcp/          # MCP server endpoints
│   │   ├── docs/             # API documentation page
│   │   └── page.tsx          # Main editor interface
│   ├── components/           # React components
│   ├── hooks/               # Custom React hooks
│   ├── lib/                 # Utility functions and document processor
│   └── types/               # TypeScript type definitions
├── public/
│   └── api-docs/           # Generated API documentation
├── scripts/
│   └── generate-tool-docs.ts # Documentation generator
└── package.json

Development

Available Scripts

• pnpm dev - Start development server
• pnpm build - Build for production
• pnpm start - Run production build
• pnpm lint - Run ESLint
• pnpm generate:docs - Generate API documentation

Technology Stack

• Next.js 15: React framework with App Router
• TypeScript: Type-safe development
• Tailwind CSS v4: Modern CSS framework
• shadcn/ui: Beautiful, accessible UI components
• @modelcontextprotocol/sdk: Official MCP SDK
• docx: Microsoft Word document processing
• mammoth: DOCX to HTML/text conversion

Using with AI Assistants

While the built-in HTTP API makes it easy to integrate with any system, you can also use it with AI assistants that support HTTP-based MCP servers.

Example Integration

// Example client code
const mcpClient = {
  async callTool(name, params) {
    const response = await fetch('http://localhost:3301/api/mcp/tools/call', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: Date.now(),
        method: 'tools/call',
        params: { name, arguments: params }
      })
    });
    const data = await response.json();
    return JSON.parse(data.result.content[0].text);
  }
};

// Use the client
const doc = await mcpClient.callTool('create_document', {
  title: 'My Document',
  content: 'Hello World'
});

Document Viewer (Iframe Embedding)

The document viewer can be embedded as an iframe to display documents in other applications:

<iframe 
  src="http://localhost:3301/viewer?id=doc_123" 
  width="100%" 
  height="600"
  frameborder="0"
></iframe>

The viewer provides a clean, read-only interface for displaying documents with:

• Document title and metadata
• Version information
• Formatted content rendering
• Dark/light mode support
• No navigation chrome (designed for embedding)

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

License

MIT License - see file for details.