Mi'kmaq Dictionary API & MCP

Mi'kmaq Dictionary API & MCP

A comprehensive RESTful API for Mi'kmaq language dictionary lookups with bidirectional search capabilities, built with TypeScript and Express.js. This API provides access to over 6,500 Mi'kmaq words with definitions, translations, and usage examples.

By our people, for our people. For the children and the elders.

This digital resource serves the Mi'kmaq community in preserving and revitalizing L'nu'k (our language) for future generations.

🌟 Features

🔄 Bidirectional Search: English ↔ Mi'kmaq translation in both directions
🎯 Random Word Learning: Get random Mi'kmaq words for daily learning
🔍 Advanced Search: Fuzzy search, exact matches, and filtered results
📚 Rich Linguistic Data: Definitions, translations, usage examples, and grammatical types
🏷️ Grammatical Classification: Proper Mi'kmaq linguistic categories (animate/inanimate, transitive/intransitive)
🚀 High Performance: In-memory indexing for sub-millisecond lookups
🐳 Docker Ready: Complete containerization with Docker Compose
🛡️ Production Security: Rate limiting, CORS, security headers, and health monitoring
📊 Analytics: Comprehensive dictionary statistics and insights
🧪 Fully Tested: 71 comprehensive tests with 100% core functionality coverage
🔌 MCP Integration: Model Context Protocol server for seamless IDE integration (Cursor, VS Code)
🤖 AI Assistant Ready: Direct access to Mi'kmaq dictionary through AI coding assistants

📚 Complete API Reference

🔍 Dictionary Lookup Endpoints

1. Mi'kmaq Word Lookup

GET /api/v1/entries/mik/<word>

Find English definitions and translations for Mi'kmaq words.

Example:

curl "http://localhost:3000/api/v1/entries/mik/samqwan"

2. English Word Lookup ✨ NEW

GET /api/v1/entries/english/<word>

Find Mi'kmaq translations for English words.

Example:

curl "http://localhost:3000/api/v1/entries/english/water"
# Returns: samqwan (Mi'kmaq word for water)

3. Random Word for Learning ✨ NEW

GET /api/v1/entries/random

Get a random Mi'kmaq word - perfect for daily language learning!

Example:

curl "http://localhost:3000/api/v1/entries/random"

🔍 Bidirectional Search Endpoints ✨ NEW

4. English to Mi'kmaq Search

GET /api/v1/search?q=<query>&type=english-to-mikmaq

Search for Mi'kmaq words using English terms.

Example:

curl "http://localhost:3000/api/v1/search?q=water&type=english-to-mikmaq&limit=5"

5. Mi'kmaq to English Search

GET /api/v1/search?q=<query>&type=mikmaq-to-english

Search for English definitions using Mi'kmaq terms.

Example:

curl "http://localhost:3000/api/v1/search?q=samqwan&type=mikmaq-to-english"

🛠️ Utility Endpoints

GET /api/v1/stats - Dictionary statistics and word counts
GET /api/v1/word-types - Available grammatical categories
GET /api/v1/health - Health check and API status
GET / - Complete API documentation and examples

📋 Query Parameters

All endpoints support these optional parameters:

exact (boolean): Exact match only (default: false)
limit (number): Maximum results to return (default: 10)
partOfSpeech (string): Filter by grammatical type
q (string): Search query (required for search endpoints)
type (string): Search direction - "english-to-mikmaq" or "mikmaq-to-english"

📊 Example API Response

[
  {
    "word": "samqwan",
    "phonetic": null,
    "phonetics": [],
    "origin": null,
    "meanings": [
      {
        "partOfSpeech": "noun",
        "definitions": [
          {
            "definition": "water",
            "example": "Nowhere is there better tasting water than in Listuguj.",
            "synonyms": [],
            "antonyms": []
          }
        ]
      }
    ]
  }
]

🔌 MCP Integration (Model Context Protocol)

The Mi'kmaq Dictionary API includes a Model Context Protocol (MCP) server that enables seamless integration with AI-powered IDEs like Cursor, allowing AI assistants to directly access Mi'kmaq language resources during development.

🌟 MCP Features

7 MCP Tools for comprehensive Mi'kmaq dictionary access
IDE Integration: Works with Cursor, VS Code, and other MCP-compatible editors
AI Assistant Access: Enable AI coding assistants to lookup, translate, and learn Mi'kmaq words
Docker Ready: Containerized MCP server with automatic API connectivity
Real-time Access: Direct API integration without additional configuration

🛠️ Available MCP Tools

lookup_mikmaq_word - Look up Mi'kmaq words and get English definitions
lookup_english_word - Find Mi'kmaq translations for English words
search_dictionary - Bidirectional fuzzy search (English ↔ Mi'kmaq)
get_random_word - Get random Mi'kmaq words for learning
get_dictionary_stats - View dictionary statistics and word counts
get_word_types - List all grammatical categories
check_api_health - Monitor API status and connectivity

🚀 Quick MCP Setup

Option 1: Docker Compose (Recommended)

# Start both API and MCP server together
docker-compose up -d

# The MCP server will be available for IDE integration
# API: http://localhost:3000
# MCP: Ready for IDE connection

Option 2: Local Development

# Start the dictionary API first
npm run dev

# In a separate terminal, start the MCP server
cd Mcp
npm install
npm run build
npm start

🔧 Cursor IDE Configuration

Add this to your Cursor MCP settings (~/.cursor/mcp_servers.json or workspace settings):

For Docker deployment:

{
  "mcpServers": {
    "mikmaq-dictionary": {
      "description": "Mi'kmaq Dictionary API integration for language preservation and learning",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--network", "mcp_mikmaq-network", 
        "mcp-mikmaq-mcp-server"
      ],
      "env": {
        "MIKMAQ_API_URL": "http://mikmaq-dictionary-api:3000",
        "MIKMAQ_API_TIMEOUT": "10000"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "mikmaq-dictionary": {
      "description": "Mi'kmaq Dictionary API integration for language preservation and learning",
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/your/project/Mcp",
      "env": {
        "MIKMAQ_API_URL": "http://localhost:3000"
      }
    }
  }
}

💬 Using MCP in Your IDE

Once configured, you can interact with the Mi'kmaq dictionary directly through your AI assistant:

Example conversations:

"Look up the Mi'kmaq word 'samqwan'"
"Find Mi'kmaq translations for 'water'"
"Give me a random Mi'kmaq word to learn today"
"Search for Mi'kmaq words related to 'ocean'"
"Show me dictionary statistics"
"What grammatical word types are available in Mi'kmaq?"

The AI assistant will use the MCP tools to provide real-time access to the dictionary, supporting language learning and cultural preservation directly in your development environment.

🧪 Testing MCP Integration

# Test MCP server connectivity
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm start

# Test a dictionary lookup
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "lookup_mikmaq_word", "arguments": {"word": "samqwan"}}}' | npm start

# Test random word generation
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_random_word", "arguments": {}}}' | npm start

📁 MCP Project Structure

Mcp/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   ├── dictionary-client.ts  # API client for dictionary service
│   └── types.ts             # TypeScript type definitions
├── dist/                    # Compiled JavaScript output
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── Dockerfile              # Container configuration
└── docker-compose.yml     # Multi-service orchestration

🚀 Setup Instructions

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18.0.0 or higher) - Download here
npm (comes with Node.js) or yarn
Docker (optional, for containerized deployment) - Download here
Git - Download here

Method 1: Quick Start with Docker (Recommended)

The fastest way to get the API running:

Clone the repository:

git clone <repository-url>
cd mikmaq-dictionary-api

Start with Docker Compose:

docker-compose up -d

Verify the API is running:

curl http://localhost:3000/api/v1/health

Test a Mi'kmaq word lookup:

curl http://localhost:3000/api/v1/entries/mik/samqwan

View API documentation: Open your browser to: http://localhost:3000

Method 2: Local Development Setup

For development and customization:

Step 1: Clone and Install

# Clone the repository
git clone <repository-url>
cd mikmaq-dictionary-api

# Install dependencies
npm install

Step 2: Development Mode

# Start development server with hot reload
npm run dev

# The API will be available at http://localhost:3000

Step 3: Production Build

# Build TypeScript to JavaScript
npm run build

# Start production server
npm start

Method 3: Manual Docker Build

If you want to build the Docker image yourself:

# Build the Docker image
docker build -t mikmaq-dictionary-api .

# Run the container
docker run -p 3000:3000 -v $(pwd)/dictionary.json:/app/dictionary.json:ro mikmaq-dictionary-api

🧪 Running Tests

Verify everything works correctly:

# Run all tests (71 comprehensive tests)
npm test

# Run tests with coverage report
npm run test -- --coverage

# Run linting
npm run lint

🔧 Configuration

Environment Variables

Create a .env file in the project root (copy from .env.example):

# Server Configuration
PORT=3000
NODE_ENV=development

# CORS Configuration  
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

Custom Port

To run on a different port:

# Using environment variable
PORT=8080 npm start

# Or modify your .env file
echo "PORT=8080" > .env
npm start

📁 Project Structure

mikmaq-dictionary-api/
├── src/                    # Source code
│   ├── controllers/        # API endpoint handlers
│   ├── services/          # Business logic
│   ├── types/             # TypeScript type definitions
│   ├── middleware/        # Express middleware
│   ├── routes/            # API routes
│   └── index.ts           # Main application entry
├── Mcp/                   # Model Context Protocol server
│   ├── src/               # MCP server source code
│   │   ├── index.ts       # Main MCP server implementation
│   │   ├── dictionary-client.ts  # API client
│   │   └── types.ts       # MCP type definitions
│   ├── dist/              # Compiled MCP server
│   ├── package.json       # MCP dependencies
│   ├── tsconfig.json      # MCP TypeScript config
│   ├── Dockerfile         # MCP container configuration
│   └── docker-compose.yml # MCP orchestration
├── tests/                 # Test suites
│   ├── services/          # Service layer tests
│   ├── controllers/       # Controller tests
│   ├── integration/       # End-to-end API tests
│   └── setup.ts          # Test configuration
├── dist/                  # Compiled JavaScript (after build)
├── dictionary.json        # Mi'kmaq language dictionary data
├── mcp.json              # MCP server configuration
├── Dockerfile            # Docker container configuration
├── docker-compose.yml    # Multi-container setup
├── package.json          # Node.js dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── jest.config.js        # Test configuration
└── LICENSE               # Mi'kmaq Cultural Heritage License

Dictionary Data

The API uses a comprehensive Mi'kmaq dictionary containing:

6,581 total words
Verb categories (72% of dictionary):
- Animate Intransitive: 2,090 entries
- Animate Transitive: 1,021 entries
- Inanimate Transitive: 855 entries
- Inanimate Intransitive: 765 entries
Noun categories (24% of dictionary):
- Inanimate Nouns: 831 entries
- Animate Nouns: 771 entries
- General Nouns: 29 entries
Other categories (4% of dictionary):
- Particles: 120 entries
- Unclassified: 83 entries
- Pronouns: 16 entries

📝 Example Usage

Basic Queries

# Get API documentation
curl http://localhost:3000/

# Health check
curl http://localhost:3000/api/v1/health

# Random Mi'kmaq word for learning
curl http://localhost:3000/api/v1/entries/random

# Dictionary statistics
curl http://localhost:3000/api/v1/stats

Word Lookups

# Mi'kmaq to English
curl "http://localhost:3000/api/v1/entries/mik/samqwan"

# English to Mi'kmaq
curl "http://localhost:3000/api/v1/entries/english/water"

# Exact word lookup
curl "http://localhost:3000/api/v1/entries/mik/samqwan?exact=true"

# Search with limit
curl "http://localhost:3000/api/v1/entries/english/water?limit=5"

Bidirectional Search

# English to Mi'kmaq search
curl "http://localhost:3000/api/v1/search?q=water&type=english-to-mikmaq&limit=3"

# Mi'kmaq to English search  
curl "http://localhost:3000/api/v1/search?q=samqwan&type=mikmaq-to-english"

# Filter by grammatical type
curl "http://localhost:3000/api/v1/search?q=water&type=english-to-mikmaq&partOfSpeech=noun%20inanimate"

🔧 Troubleshooting

Common Issues

Port Already in Use

# Error: EADDRINUSE: address already in use :::3000
# Solution: Use a different port
PORT=8080 npm start

Dictionary Not Loading

# Error: Failed to load Mi'kmaq dictionary
# Solution: Ensure dictionary.json exists in project root
ls -la dictionary.json

# If missing, ensure you have the complete repository
git status

Tests Failing

# Run tests in verbose mode to see details
npm test -- --verbose

# Clear Jest cache if needed
npx jest --clearCache
npm test

Docker Issues

# Stop all containers and restart
docker-compose down
docker-compose up -d

# View container logs
docker-compose logs -f

# Rebuild containers
docker-compose build --no-cache
docker-compose up -d

MCP Integration Issues

# Test MCP server connectivity
cd Mcp
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm start

# Check if dictionary API is accessible from MCP server
curl http://localhost:3000/api/v1/health

# Verify MCP server Docker network
docker network ls | grep mcp
docker-compose logs mikmaq-mcp-server

# Test MCP tools directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_random_word", "arguments": {}}}' | npm start

Cursor IDE Integration Issues

# Verify MCP configuration file location
ls ~/.cursor/mcp_servers.json

# Check Cursor logs for MCP connection errors
# Restart Cursor after MCP configuration changes

# Test MCP server independently
cd Mcp && npm start

Performance Tips

For Large Scale Usage

# Use production mode
NODE_ENV=production npm start

# Enable clustering (modify package.json)
npm install pm2 -g
pm2 start dist/index.js -i max

Memory Optimization

The API loads all 6,581 words into memory for fast lookups. For memory-constrained environments:

Minimum RAM: 512MB
Recommended RAM: 1GB+
Docker memory limit: --memory=1g

API Response Times

Word lookups: < 1ms (in-memory)
Search queries: 1-5ms (depending on complexity)
Random words: < 1ms
Statistics: < 1ms

Environment Variables

Copy .env.example to .env and configure:

PORT=3000
NODE_ENV=development
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

Docker Commands

API Only

# Build image
docker build -t mikmaq-dictionary-api .

# Run container
docker run -p 3000:3000 -v $(pwd)/dictionary.json:/app/dictionary.json:ro mikmaq-dictionary-api

# Using Docker Compose
docker-compose up -d        # Start services
docker-compose logs -f      # View logs
docker-compose down         # Stop services

API + MCP Server

# Start both API and MCP server
docker-compose up -d

# View MCP server logs
docker-compose logs -f mikmaq-mcp-server

# View API logs
docker-compose logs -f mikmaq-dictionary-api

# Stop all services
docker-compose down

# Rebuild MCP server
cd Mcp
docker build -t mcp-mikmaq-mcp-server .
cd ..
docker-compose up -d

API Response Format

The API follows the structure of dictionary APIs like DictionaryAPI.dev:

interface DictionaryApiResponse {
  word: string;
  phonetic?: string;
  phonetics: Phonetic[];
  origin?: string;
  meanings: Meaning[];
}

Rate Limiting

100 requests per 15 minutes per IP address
Rate limit headers included in responses
Configurable via environment variables

Error Responses

{
  "title": "No Definitions Found",
  "message": "Sorry pal, we couldn't find definitions for the word you were looking for.",
  "resolution": "You can try the search again at later time or head to the web instead."
}

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

Mi'kmaq Language Preservation License (MLPL) - see LICENSE file for details.

This project operates under a special license created by our people, for our people, ensuring that this digital resource serves the Mi'kmaq community while respecting our cultural sovereignty.

🏛️ Cultural Heritage & License

This project is dedicated to the preservation and revitalization of Mi'kmaq language and culture. It operates under a Mi'kmaq Cultural Heritage License that ensures respectful use and community benefit.

For Our People, By Our People

This API is created:

🧒 For the Children: Ensuring future generations can learn Mi'kmawisimk in the digital age
👴 For the Elders: Honoring knowledge keepers who preserved this language through generations
🤝 For the Community: Supporting language revitalization and cultural continuity
🏛️ For the Nation: Strengthening Mi'kmaq identity and sovereignty through linguistic preservation

Cultural Responsibilities

When using this API, please:

✅ Acknowledge the Mi'kmaq Nation as the source of language knowledge
✅ Respect the cultural context and sacred nature of language preservation
✅ Support Mi'kmaq language revitalization efforts when possible
✅ Recognize that language is living culture, not just data
❌ Do not use for purposes harmful or disrespectful to Mi'kmaq people
❌ Do not claim ownership of Mi'kmaq language or culture

🤝 Acknowledgments

Wela'lioq (Thank You) to:

Mi'kmaq Elders and knowledge keepers who preserved Mi'kmawisimk through generations
Mi'kmaq educators and community members working on language revitalization
All those who understand that technology should serve Indigenous communities
The traditional territories of Mi'kma'ki where this language has been spoken for millennia

"Msit No'kmaq" - All My Relations

📜 License

This project uses a dual licensing approach:

Mi'kmaq Cultural Heritage License: Ensures respectful use and community benefit
MIT License: Provides technical implementation flexibility

The cultural license takes precedence for appropriate use of Mi'kmaq language data. See LICENSE for complete terms.

🌐 Contributing

We welcome contributions that:

Support Mi'kmaq language preservation and education
Improve accessibility for language learners
Enhance technical performance and reliability
Follow cultural protocols and community guidance

Please engage respectfully and prioritize community needs in any contributions.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
Mcp		Mcp
src		src
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Mikmaq_State_Flag.png		Mikmaq_State_Flag.png
README.md		README.md
dictionary.json		dictionary.json
docker-compose.yml		docker-compose.yml
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Mi'kmaq Dictionary API & MCP

🌟 Features

📚 Complete API Reference

🔍 Dictionary Lookup Endpoints

1. Mi'kmaq Word Lookup

2. English Word Lookup ✨ NEW

3. Random Word for Learning ✨ NEW

🔍 Bidirectional Search Endpoints ✨ NEW

4. English to Mi'kmaq Search

5. Mi'kmaq to English Search

🛠️ Utility Endpoints

📋 Query Parameters

📊 Example API Response

🔌 MCP Integration (Model Context Protocol)

🌟 MCP Features

🛠️ Available MCP Tools

🚀 Quick MCP Setup

Option 1: Docker Compose (Recommended)

Option 2: Local Development

🔧 Cursor IDE Configuration

💬 Using MCP in Your IDE

🧪 Testing MCP Integration

📁 MCP Project Structure

🚀 Setup Instructions

Prerequisites

Method 1: Quick Start with Docker (Recommended)

Method 2: Local Development Setup

Step 1: Clone and Install

Step 2: Development Mode

Step 3: Production Build

Method 3: Manual Docker Build

🧪 Running Tests

🔧 Configuration

Environment Variables

Custom Port

📁 Project Structure

Dictionary Data

📝 Example Usage

Basic Queries

Word Lookups

Bidirectional Search

🔧 Troubleshooting

Common Issues

Port Already in Use

Dictionary Not Loading

Tests Failing

Docker Issues

MCP Integration Issues

Cursor IDE Integration Issues

Performance Tips

For Large Scale Usage

Memory Optimization

API Response Times

Environment Variables

Docker Commands

API Only

API + MCP Server

API Response Format

Rate Limiting

Error Responses

Contributing

License

🏛️ Cultural Heritage & License

For Our People, By Our People

Cultural Responsibilities

🤝 Acknowledgments

📜 License

🌐 Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks