Code V MCP Server

A Model Context Protocol (MCP) server for processing Code V optical design scripts and PDF documents. This server allows Claude AI to access, analyze, and work with your Code V files and technical documentation.

What is Code V?

Code V is an optical design and analysis software used for designing optical systems. This MCP server helps you work with Code V sequence files (.seq) and macro files (.mac) alongside related PDF documentation.

Features

• Code V Script Management

  • List all Code V files in your project directory
  • Read and display Code V script contents
  • Analyze Code V syntax and command usage
  • Search for specific commands across all files

• PDF Processing

  • List PDF documents
  • Extract and read PDF text content
  • Access technical documentation

• Resource Access

  • Expose Code V files as MCP resources
  • Expose PDF files as MCP resources

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Ubuntu/Linux environment (or WSL on Windows)

Installation

1. Clone or Create the Project

# If you have a git repository
git clone <your-repo-url>
cd codev-mcp-server

# Or if you're setting up locally
mkdir -p ~/codev-mcp-server
cd ~/codev-mcp-server

2. Install Dependencies

npm install

3. Build the Project

npm run build

4. Set Up Your Directories

Create directories for your Code V files and PDFs:

mkdir -p ~/codev-projects
mkdir -p ~/codev-pdfs

Or set custom paths using environment variables (see Configuration below).

Configuration

The server uses environment variables to locate your files:

• CODEV_DIR: Directory containing Code V files (default: ~/codev-projects)
• PDF_DIR: Directory containing PDF files (default: ~/codev-pdfs)

Setting Environment Variables

Add to your ~/.bashrc or ~/.zshrc:

export CODEV_DIR="/path/to/your/codev/files"
export PDF_DIR="/path/to/your/pdf/files"

Then reload:

source ~/.bashrc

Connecting to Claude Desktop

1. Install Claude Desktop

Download and install Claude Desktop from claude.ai

2. Configure Claude Desktop

Edit the Claude Desktop configuration file:

On Linux:

nano ~/.config/Claude/claude_desktop_config.json

On macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%\Claude\claude_desktop_config.json

3. Add MCP Server Configuration

Add your server to the configuration:

{
  "mcpServers": {
    "codev": {
      "command": "node",
      "args": ["/full/path/to/codev-mcp-server/build/index.js"],
      "env": {
        "CODEV_DIR": "/home/yourusername/codev-projects",
        "PDF_DIR": "/home/yourusername/codev-pdfs"
      }
    }
  }
}

Important: Use absolute paths!

4. Restart Claude Desktop

Close and reopen Claude Desktop completely for changes to take effect.

Usage Examples

Once connected, you can ask Claude:

Code V Operations

"List all my Code V files"
"Read the lens_design.seq file"
"Analyze the syntax of my doublet.seq script"
"Search for all RD commands in my Code V files"
"What surfaces are defined in my zoom_lens.seq?"

PDF Operations

"List all PDF files"
"Read the contents of optical_design_guide.pdf"
"Find information about aberrations in my PDF documentation"

Combined Analysis

"Compare the lens design in doublet.seq with the theory in my optics_textbook.pdf"
"What Code V commands are used in my project and what do they do according to my documentation?"

Available Tools

The server provides these tools to Claude:

1. list_codev_files - Lists all .seq and .mac files
2. read_codev_file - Reads a specific Code V file
3. analyze_codev_syntax - Analyzes commands and structure
4. list_pdf_files - Lists all PDF files
5. read_pdf_content - Extracts text from PDFs
6. search_codev_commands - Searches for specific commands

File Organization

Organize your files like this:

~/codev-projects/
├── lens_design.seq
├── doublet.seq
├── zoom_lens.seq
└── macros/
    └── optimization.mac

~/codev-pdfs/
├── codev_reference_manual.pdf
├── optical_design_textbook.pdf
└── project_specifications.pdf

Troubleshooting

Server Not Appearing in Claude

1. Check that the path in claude_desktop_config.json is absolute
2. Verify the build was successful: npm run build
3. Check Claude Desktop logs:
   • Linux: ~/.config/Claude/logs/
   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\

Files Not Found

1. Verify directories exist: ls -la ~/codev-projects
2. Check environment variables: echo $CODEV_DIR
3. Ensure files have correct extensions (.seq, .mac, .pdf)
4. Check file permissions: chmod 644 ~/codev-projects/*

Permission Errors

chmod +x build/index.js
chmod -R 755 ~/codev-projects
chmod -R 755 ~/codev-pdfs

Development

Watch Mode

For development with auto-rebuild:

npm run watch

Testing Locally

Test the server directly:

npm start

Then type in stdin (press Enter after each line):

{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

Code V Syntax Reference

Common Code V commands this server can help with:

• RD - Radius of curvature
• TH - Thickness
• GLA - Glass material
• APS - Aperture stop
• WL - Wavelength
• OBB - Object distance
• ADE - Automatic design

Extending the Server

Adding New Tools

Edit src/index.ts and add to the tools array in ListToolsRequestSchema:

{
  name: "your_tool_name",
  description: "What your tool does",
  inputSchema: {
    type: "object",
    properties: {
      // your parameters
    },
  },
}

Then add the handler in the CallToolRequestSchema switch statement.

Adding Better PDF Processing

For production use, consider adding pdf-parse:

npm install pdf-parse
npm install --save-dev @types/pdf-parse

Then update the extractPdfText function to use proper PDF parsing.

Security Notes

• The server only accesses files in configured directories
• No network access is required
• All processing happens locally
• Files are never modified by the server

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues or questions:

• Check the troubleshooting section above
• Review MCP documentation: https://modelcontextprotocol.io
• Check Claude Desktop logs for error messages

Version History

• 1.0.0 - Initial release
  • Code V file listing and reading
  • PDF text extraction
  • Command search functionality
  • Syntax analysis

Acknowledgments

• Built with the Model Context Protocol SDK
• Designed for optical design workflows
• Supports Code V optical design software