Earth616 Vocabulary Service

A Model Context Protocol (MCP) server for accessing the Earth616 Defense Supply Chain and Documentation Ontology (DSCDO).

Quick Start

Option 1: Local Development

1. Build the service:

   npm install
   npm run build
   

2. Test the service locally:

   # Test that it starts up
   node dist/index.js
   # Should output: "Earth616 MCP Vocabulary Server running on stdio"
   # Press Ctrl+C to exit
   

Option 2: Docker Development (Recommended)

1. Start the full stack:

   npm run docker:up
   

   This starts:

   • Nginx server on port 8080 (serving example ontology files)
   • MCP vocabulary service (connected to nginx)

2. Test the stack:

   # Test ontology server
   curl http://localhost:8080/health
   
   # View example files
   curl http://localhost:8080/example/
   

3. View logs:

   npm run docker:logs
   

4. Stop the stack:

   npm run docker:down
   

5. Connect to Claude Desktop:

   Copy the configuration from claude_desktop_config.json to your Claude Desktop configuration file:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   Or merge with existing config:

   {
     "mcpServers": {
       "earth616-vocab": {
         "command": "node",
         "args": ["/full/path/to/earth616_mcp_vocab_service/dist/index.js"],
         "env": {
           "NODE_ENV": "development"
         }
       }
     }
   }
   

6. Test in Claude Desktop:

   After restarting Claude Desktop, you should be able to use these tools:

   • hello_vocab - Simple test tool
   • get_ontology_info - Basic ontology information
   • test_ontology_server - Test connectivity to the ontology file server
   • list_example_files - List available example files

Current Status

This is a minimal MCP server with Docker integration. Available tools:

• hello_vocab: Echo back a message (testing connectivity)
• get_ontology_info: Get basic information about the Earth616 ontology
• test_ontology_server: Test connectivity to the ontology file server
• list_example_files: List available example ontology files

The Docker setup provides:

• nginx: Serves ontology files with proper content types
• MCP service: Connects to nginx and provides vocabulary access
• Health checks: /health endpoint for service monitoring

Next Steps

Following the iterative approach outlined in VOCAB_SERVICE_PLAN.md, we'll gradually add:

1. File-based vocabulary term lookup
2. URI resolution capabilities
3. W3C PROF Profile navigation
4. Complete vocabulary dataset access
5. Cross-layer navigation tools

Development

Local Development

• npm run dev - Watch mode for development
• npm run build - Build TypeScript
• npm start - Run the built server

Docker Development

• npm run docker:build - Build Docker image
• npm run docker:up - Start full stack (detached)
• npm run docker:down - Stop full stack
• npm run docker:logs - View MCP service logs
• npm run docker:test - Quick health check test

Development Workflow

1. Make changes to src/index.ts
2. npm run docker:up to test with full stack
3. Use Claude Desktop tools to test functionality
4. npm run docker:logs to debug issues
5. npm run docker:down when done

The server runs on stdio and communicates with Claude Desktop via the MCP protocol. The Docker setup simulates the full production environment locally.