Earth616 MCP 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.