OpenSyllabus MCP Server

A Model Context Protocol (MCP) server for accessing OpenSyllabus.org data, designed for "constellating" - discovering connections between academic works, authors, and ideas to build meaningful curricula and explore intellectual networks.

Features

• Explore individual works and their academic connections
• Discover an author's entire body of work and their intellectual network
• Find lesser-known "gem" works with strong pedagogical connections
• Trace connection paths between seemingly unrelated works
• Search actual course syllabi to understand real-world usage
• MCP integration for seamless use with AI models like Claude

Installation

Prerequisites

• Node.js 18 or later
• Access to OpenSyllabus.org cookies (from a logged-in browser session)

Quick Install

# Install globally
npm install -g opensyllabus-mcp

# Or use without installing
npx opensyllabus-mcp

Manual Installation

1. Clone this repository
2. Install dependencies:

   cd opensyllabus-mcp
   npm install

3. Make the script executable:

   chmod +x index.js

Getting Authentication Cookies

To use this tool, you'll need authentication cookies from OpenSyllabus. Follow these steps:

1. Visit OpenSyllabus.org and sign in to your account
2. Open Developer Tools (F12 or Right-click > Inspect)
3. Go to the Application tab (Chrome) or Storage tab (Firefox)
4. In the left sidebar, expand "Cookies" and click on "https://opensyllabus.org"
5. Find these two cookies and copy their values:
   • __Secure-csrftoken
   • __Secure-sessionid

Example Cookie Values

Your cookies will look something like this:

• csrftoken: Oi0xta1VfoAevPVItF6EVW5tuRnrXLRo
• sessionid: 2oszpy7aut7w5csz5zdi8wjr9xtt1nh5

Configuration

Once you have both cookie values, configure them using one of these methods:

Option 1: Claude Desktop or Other MCP Client Configuration

To use this server with Claude Desktop, add the following to your Claude configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "opensyllabus": {
      "command": "npx",
      "args": [
        "-y",
        "opensyllabus-mcp"
      ],
      "env": {
        "OPENSYLLABUS_CSRFTOKEN": "your-csrftoken-value",
        "OPENSYLLABUS_SESSIONID": "your-sessionid-value",
        "OPENSYLLABUS_CACHE_DIR": "/path/to/cache",  // Optional
        "OPENSYLLABUS_DEBUG": "false"                 // Optional
      }
    }
  }
}

For best performance with global installation:

{
  "mcpServers": {
    "opensyllabus": {
      "command": "opensyllabus-mcp",
      "env": {
        "OPENSYLLABUS_CSRFTOKEN": "your-csrftoken-value",
        "OPENSYLLABUS_SESSIONID": "your-sessionid-value"
      }
    }
  }
}

Option 2: Environment File (Recommended for Development)

Create a .env file in the project root:

OPENSYLLABUS_CSRFTOKEN=your-csrftoken-value
OPENSYLLABUS_SESSIONID=your-sessionid-value

Note: Copy .env.example to .env and fill in your values.

Cookie Lifetimes

Based on OpenSyllabus's default settings:

• Session ID: Expires after ~15 days
• CSRF Token: Expires after 1 year

You'll typically only need to update the session ID every couple of weeks. The CSRF token rarely needs updating.

Configuration Options

The MCP server supports various configuration options for performance and customization:

Environment Variables

# Required authentication
OPENSYLLABUS_CSRFTOKEN=your-csrftoken-value
OPENSYLLABUS_SESSIONID=your-sessionid-value

# Performance optimization
OPENSYLLABUS_CACHE_DIR=~/.opensyllabus-mcp-cache  # Custom cache directory
OPENSYLLABUS_ENABLE_CACHE=true                     # Enable persistent caching (default: true)
OPENSYLLABUS_DEBUG=true                            # Enable performance debugging logs

# Connection settings
OPENSYLLABUS_TIMEOUT=30000                         # Request timeout in milliseconds
OPENSYLLABUS_MAX_RETRIES=2                         # Maximum retry attempts

Performance Features

1. Persistent Caching: API responses are cached for 7 days by default, dramatically improving performance for repeated queries
2. Hybrid Cache: Uses both in-memory and disk caching for optimal speed
3. Response Compression: Automatically compresses large responses
4. Connection Pooling: Manages concurrent requests efficiently

Cache Management

The cache is stored in ~/.opensyllabus-mcp-cache/ by default. You can:

# Change cache location
export OPENSYLLABUS_CACHE_DIR=/custom/path

# Disable caching (not recommended)
export OPENSYLLABUS_ENABLE_CACHE=false

# Clear cache manually
rm -rf ~/.opensyllabus-mcp-cache/

Installation Methods (by Performance)

1. Global Install (Fastest)

   npm install -g opensyllabus-mcp
   opensyllabus-mcp

2. npx with Cache (Convenient)

   npx opensyllabus-mcp  # Uses persistent cache

3. Development (Most Control)

   git clone <repo>
   cd opensyllabus-mcp
   npm install
   npm start

MCP Tools

The server provides the following tools focused on exploration and constellating:

exploreWork

THE MAIN CONSTELLATING TOOL: Explore any work to reveal its rich network of connections. Shows co-taught texts categorized as classics, strong connections, emerging works, and interdisciplinary bridges. Includes full metadata from OpenLibrary.

Parameters:

• identifier (string, required): Work ID, ISBN, or title to explore
• includeConnections (boolean, optional): Whether to include detailed co-assignment connections (default: true)
• maxConnections (number, optional): Maximum number of connections to return (max: 20, default: 10)

Example:

{
  "tool": "exploreWork",
  "parameters": {
    "identifier": "The Great Gatsby",
    "includeConnections": true,
    "maxConnections": 15
  }
}

exploreAuthor

EXPLORE AN AUTHOR'S CONSTELLATION: Dive deep into an author's body of work and discover what's taught alongside their books. Reveals common co-assignments across all their works, showing how their ideas connect to the broader academic landscape.

Parameters:

• authorName (string, required): Author name to explore
• includeWorks (boolean, optional): Whether to include the author's works (default: true)
• includeConnections (boolean, optional): Whether to include connections for each work (default: false)
• maxWorks (number, optional): Maximum number of works to return (max: 10, default: 5)
• maxConnectionsPerWork (number, optional): Maximum connections per work when includeConnections=true (max: 5, default: 3)

Example:

{
  "tool": "exploreAuthor",
  "parameters": {
    "authorName": "Jane Jacobs",
    "includeWorks": true,
    "includeConnections": true,
    "maxWorks": 3
  }
}

discoverGems

FIND HIDDEN TREASURES: Discover lesser-known but pedagogically valuable works connected to any text. Uses adaptive percentile-based filtering to find gems relative to each field's citation norms - perfect for finding diverse perspectives, unique voices, and non-mainstream approaches.

Parameters:

• workId (string, optional): ID of the work to find gems related to
• workIdentifier (string, optional): Work title, ISBN, or ID to find gems related to
• maxResults (number, optional): Maximum number of gems to return (default: 10)
• citationThreshold (number, optional): Absolute maximum citations for a work to be considered a 'gem' (default: 1000)
• citationPercentile (number, optional): Percentile threshold for citations (e.g., 30 = bottom 30% of citations within co-assigned works) (default: 30)

Example:

{
  "tool": "discoverGems",
  "parameters": {
    "workIdentifier": "The Death and Life of Great American Cities",
    "maxResults": 5,
    "citationPercentile": 30
  }
}

findConnections

TRACE INTELLECTUAL PATHS: Discover how two seemingly unrelated works are connected through chains of co-assignments. Perfect for finding unexpected links between disciplines or building innovative curricula that bridge different areas.

Parameters:

• fromWork (string, required): Starting work (ID, ISBN, or title)
• toWork (string, required): Target work (ID, ISBN, or title)
• maxHops (number, optional): Maximum steps in the connection chain (default: 3)
• maxPaths (number, optional): Maximum number of paths to find (default: 5)

Example:

{
  "tool": "findConnections",
  "parameters": {
    "fromWork": "The Great Gatsby",
    "toWork": "The Structure of Scientific Revolutions",
    "maxHops": 4
  }
}

searchSyllabi

Find actual course syllabi to understand pedagogical contexts. Reveals how works are taught together and in what academic settings.

Parameters:

• query (string, optional): Free text search within syllabi content
• author (string, optional): Filter by author name
• work (string, optional): Filter by work/book title
• institution (string, optional): Filter by institution name
• country (string, optional): Filter by country code
• size (number, optional): Number of results to return (default: 20)

Example:

{
  "tool": "searchSyllabi",
  "parameters": {
    "author": "Jane Jacobs",
    "institution": "Harvard",
    "size": 10
  }
}

Response Structures

exploreWork Response

{
  "work": {
    "id": "123456",
    "title": "The Great Gatsby",
    "authors": ["F. Scott Fitzgerald"],
    "year": 1925,
    "enrichedMetadata": {
      "isbn": "9780123456789",
      "publisher": "Scribner",
      "genre": "Fiction",
      "openLibraryUrl": "..."
    }
  },
  "connections": {
    "classics": [...],
    "strongConnections": [...],
    "emergingWorks": [...],
    "interdisciplinary": [...]
  },
  "metadata": {
    "totalConnections": 45,
    "connectionStrength": "high",
    "academicImpact": "Widely taught across literature departments"
  }
}

discoverGems Response

{
  "gems": {
    "veryStrongConnections": [...],
    "crossDisciplinary": [...],
    "recentGems": [...],
    "classicGems": [...],
    "all": [...]
  },
  "metadata": {
    "startingWork": {
      "id": "123456",
      "title": "The Death and Life of Great American Cities",
      "citationCount": 3669
    },
    "totalCoAssignments": 125,
    "candidatesAnalyzed": 40,
    "citationPercentileUsed": 30,
    "citationThreshold": 2275,
    "gemsFound": 5,
    "citationDistribution": {
      "min": 2153,
      "max": 3379,
      "median": 2552
    },
    "reasoning": "Found works in the bottom 30% of citations among co-assigned texts (threshold: 2275 citations)"
  }
}

Error Handling

All tools include error handling and will return a response even when errors occur:

{
  "error": "Missing required cookies. Please set csrftoken and sessionid in the config file or environment variables.",
  "work": null,
  "connections": {},
  "metadata": {}
}

Troubleshooting

Authentication Errors

If you encounter authentication errors after a period of use:

1. Visit OpenSyllabus.org and confirm you're still logged in
2. Extract fresh cookie values using the Application/Storage tab method
3. Update your configuration with the new cookie values

Performance Issues

If the tool is running slowly:

1. Enable Persistent Caching (enabled by default)

   export OPENSYLLABUS_ENABLE_CACHE=true

2. Check Cache Status

   # View cache directory size
   du -sh ~/.opensyllabus-mcp-cache/
      
   # Clear cache if needed
   rm -rf ~/.opensyllabus-mcp-cache/

3. Use Global Installation

   npm install -g opensyllabus-mcp

4. Enable Debug Logging

   export OPENSYLLABUS_DEBUG=true

5. Common Issues:

   • First run after installation will be slower (building cache)
   • npx downloads the package each time (use global install instead)
   • Large result sets may take longer (use smaller maxResults values)

Cache Configuration

The tool uses a hybrid caching system:

• Memory cache: Fast access during current session (1 hour TTL)
• Disk cache: Persists across sessions (7 day TTL)
• Location: ~/.opensyllabus-mcp-cache/ by default

Development

For development, you can run tests from the tests directory:

cd tests
node test-discover-gems.js
node test-explore-work.js
# etc.

License

MIT