JavaScript SDK

npm install hmdl

yarn add hmdl

import { HeimdallClient, traceMCPTool } from 'hmdl';

// Initialize with explicit configuration
const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "your-org-id",
  projectId: "your-project-id",
  serviceName: "my-mcp-server",
  environment: "development"
});

const searchDocuments = traceMCPTool(
  async (query: string, limit: number = 10) => {
    const results = await performSearch(query, limit);
    return {
      results,
      query,
      total: results.length
    };
  },
  { 
    name: "search-documents",
    paramNames: ["query", "limit"]
  }
);

// Call your tool normally
const result = await searchDocuments("machine learning", 5);

// At the end of your application
await client.flush();

const myTool = traceMCPTool(
  async (arg1: string, arg2: number) => {
    return { result: "data" };
  },
  {
    name: "my-tool",           // Custom span name (required)
    paramNames: ["arg1", "arg2"], // Parameter names for display
    captureInput: true,        // Capture input arguments (default: true)
    captureOutput: true        // Capture return value (default: true)
  }
);

import { observe } from 'hmdl';

const fetchUser = observe(
  async (userId: string) => {
    // Fetch user from database
    return { id: userId, name: "John" };
  },
  { name: "fetch-user-data" }
);

const processPayment = observe(
  async (cardNumber: string, amount: number) => {
    // Process payment
    return true;
  },
  { 
    name: "process-payment",
    captureOutput: false  // Don't capture sensitive output
  }
);

const riskyOperation = traceMCPTool(
  async (data: string) => {
    if (!data) {
      throw new Error("Data cannot be empty");
    }
    return { processed: data };
  },
  { name: "risky-operation", paramNames: ["data"] }
);

try {
  await riskyOperation("");
} catch (error) {
  // Error is captured in the trace
}

await client.flush();  // Don't forget to flush!

import { HeimdallClient, traceMCPTool, observe } from 'hmdl';

// Configure via environment variables
process.env.HEIMDALL_ENDPOINT = "http://localhost:4318";
process.env.HEIMDALL_ORG_ID = "my-org";
process.env.HEIMDALL_PROJECT_ID = "my-project";

// Initialize client
const client = new HeimdallClient({
  serviceName: "document-mcp-server",
  environment: "production"
});

// Your MCP tools
const searchDocuments = traceMCPTool(
  async (query: string, limit: number = 10) => {
    const results = await db.search(query, limit);
    return { results, count: results.length };
  },
  { name: "search-documents", paramNames: ["query", "limit"] }
);

const getDocument = traceMCPTool(
  async (docId: string) => {
    const doc = await db.get(docId);
    if (!doc) {
      throw new Error(`Document ${docId} not found`);
    }
    return doc;
  },
  { name: "get-document", paramNames: ["docId"] }
);

const createDocument = traceMCPTool(
  async (title: string, content: string) => {
    const doc = await db.create({ title, content });
    return { id: doc.id, created: true };
  },
  { name: "create-document", paramNames: ["title", "content"] }
);

// Internal helper with tracing
const validateQuery = observe(
  (query: string): boolean => {
    return query.length >= 3;
  },
  { name: "validate-query" }
);

// Main execution
async function main() {
  try {
    // Run your MCP server logic
    const result = await searchDocuments("test query", 5);
    console.log(result);
  } finally {
    // Always flush before exit
    await client.flush();
  }
}

main();

// Type inference works correctly
const search = traceMCPTool(
  async (query: string, limit: number): Promise<SearchResult> => {
    // ...
  },
  { name: "search", paramNames: ["query", "limit"] }
);

// search is typed as: (query: string, limit: number) => Promise<SearchResult>