What is Mcp Vocabulary Service

The mcp_vocabulary_service is a Model Context Protocol (MCP) server designed for accessing the Earth616 Defense Supply Chain and Documentation Ontology (DSCDO).

Use cases

Use cases include testing ontology information, verifying connectivity to ontology servers, and listing available example files for developers and users in the Earth616 ecosystem.

How to use

To use the mcp_vocabulary_service, you can either build it locally using npm commands or run it in a Docker container. For local development, install dependencies and run the service. For Docker, use the provided npm scripts to start the full stack and test the service.

Key features

Key features include local and Docker-based deployment options, health checks for the ontology server, example file serving, and integration with Claude Desktop for enhanced functionality.

Where to use

The mcp_vocabulary_service is applicable in fields such as supply chain management, defense logistics, and any domain requiring structured documentation and ontology management.

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.