metadata-config.md

Metadata & Configuration

← Back to Index

---

Query project metadata and configuration settings for stages, categories, tags, users, and importance levels.

Table of Contents

1. Workflow Stages
2. Categories
3. Tags
4. Importance Levels
5. Users

---

Workflow Stages

list_stages

List workflow stages (Planned, In Progress, Testing, Completed, etc.).

Parameters:

• projectId (number, optional): Project ID
• offset (number, optional): Pagination offset
• limit (number, optional): Max items (default: 50, max: 200)

Returns: { items, total, offset, limit, hasMore }

Response Fields (per stage):

• stageId: Stage identifier
• name: Stage name
• order: Display order
• categoryId: Workflow category

Example:

const stages = await callTool('list_stages', {
  projectId: 230954
});

stages.items.forEach(stage => {
  console.log(`${stage.order}. ${stage.name} (ID: ${stage.stageId})`);
});

// Output:
// 1. Planned (ID: 1)
// 2. In Progress (ID: 2)
// 3. Testing (ID: 3)
// 4. Done (ID: 4)

Use Cases:

• Get stage IDs for update_work_items
• Find "In Progress" stage ID for start_task override
• Display workflow visualization

---

Categories

list_categories

List work item categories (Task, Bug, Feature, etc.).

Parameters:

• projectId (number, optional): Project ID
• offset (number, optional): Pagination offset
• limit (number, optional): Max items (default: 50, max: 200)

Returns: { items, total, offset, limit, hasMore }

Response Fields (per category):

• categoryId: Category identifier
• name: Category name
• color: Hex color code
• icon: Icon name

Example:

const categories = await callTool('list_categories', {
  projectId: 230954
});

categories.items.forEach(cat => {
  console.log(`${cat.name} (ID: ${cat.categoryId}, Color: ${cat.color})`);
});

// Output:
// Programming (ID: 1, Color: #4CAF50)
// Design (ID: 2, Color: #2196F3)
// Bug (ID: 5, Color: #F44336)

Name Resolution:

Categories support name resolution in create_work_items and update_work_items:

// These are equivalent:
categoryId: 'programming'  // Name
categoryId: 1              // ID

// Supported names:
// 'programming', 'design', 'writing', 'ideas', 'bug'

---

Tags

list_tags

List project tags.

Parameters:

• projectId (number, optional): Project ID
• offset (number, optional): Pagination offset
• limit (number, optional): Max items (default: 50, max: 200)

Returns: { items, total, offset, limit, hasMore }

Response Fields (per tag):

• tagId: Tag identifier
• name: Tag name
• color: Hex color code (optional)

Example:

const tags = await callTool('list_tags', {
  projectId: 230954
});

tags.items.forEach(tag => {
  console.log(`#${tag.name} (ID: ${tag.tagId})`);
});

// Output:
// #backend (ID: 1)
// #frontend (ID: 2)
// #urgent (ID: 3)

Name Resolution & Auto-Create:

Tags support name resolution with automatic creation:

// Update work item with tag names
await callTool('update_work_items', {
  items: [{
    workItemId: 123,
    tagIds: ['backend', 'urgent', 'new-tag']  // Auto-creates 'new-tag'!
  }]
});

// Response warnings:
// warnings: ["Auto-created tag: 'new-tag'"]

Common Use Cases:

• Map tag names to IDs for queries
• Display tag palette for UI
• Validate tag names before using

---

Importance Levels

list_importance_levels

List priority/importance levels (Urgent, High, Normal, Low).

Parameters:

• projectId (number, optional): Project ID
• offset (number, optional): Pagination offset
• limit (number, optional): Max items (default: 50, max: 200)

Returns: { items, total, offset, limit, hasMore }

Response Fields (per level):

• importanceLevelId: Level identifier
• name: Level name
• value: Numeric priority value

Example:

const levels = await callTool('list_importance_levels', {
  projectId: 230954
});

levels.items.forEach(level => {
  console.log(`${level.name} (ID: ${level.importanceLevelId}, Value: ${level.value})`);
});

// Output:
// Urgent (ID: 1, Value: 1)
// High (ID: 2, Value: 2)
// Normal (ID: 3, Value: 3)
// Low (ID: 4, Value: 4)

Name Resolution:

Importance levels support name resolution:

// These are equivalent:
importanceLevelId: 'high'  // Name
importanceLevelId: 2       // ID

// Supported names:
// 'urgent', 'high', 'normal', 'low'

---

Users

list_users

List users in a project.

Parameters:

• projectId (number, optional): Project ID
• offset (number, optional): Pagination offset
• limit (number, optional): Max items (default: 50, max: 200)

Returns: { items, total, offset, limit, hasMore }

Response Fields (per user):

• userId: User identifier
• name: Display name
• email: Email address
• role: Project role

Example:

const users = await callTool('list_users', {
  projectId: 230954
});

users.items.forEach(user => {
  console.log(`${user.name} (${user.email}) - Role: ${user.role}`);
});

// Output:
// John Doe (john@example.com) - Role: Admin
// Jane Smith (jane@example.com) - Role: Developer

Use Cases:

• Get user IDs for task assignment
• Display team member list in UI
• Validate user permissions

---

Common Patterns

Initialize Project Metadata

// Load all metadata on startup
const [stages, categories, tags, levels, users] = await Promise.all([
  callTool('list_stages', { projectId }),
  callTool('list_categories', { projectId }),
  callTool('list_tags', { projectId }),
  callTool('list_importance_levels', { projectId }),
  callTool('list_users', { projectId })
]);

// Build lookup maps
const stageMap = Object.fromEntries(
  stages.items.map(s => [s.name, s.stageId])
);

const categoryMap = Object.fromEntries(
  categories.items.map(c => [c.name.toLowerCase(), c.categoryId])
);

const tagMap = Object.fromEntries(
  tags.items.map(t => [t.name, t.tagId])
);

// Use in application
const inProgressStageId = stageMap['In Progress'];
const bugCategoryId = categoryMap['bug'];

---

Display Workflow Board

const stages = await callTool('list_stages', { projectId: 230954 });
const tasks = await callTool('list_work_items', { projectId: 230954 });

// Group tasks by stage
const tasksByStage = {};
stages.items.forEach(stage => {
  tasksByStage[stage.name] = tasks.items.filter(
    task => task.stageId === stage.stageId
  );
});

// Display kanban board
stages.items.forEach(stage => {
  console.log(`\n=== ${stage.name} (${tasksByStage[stage.name].length}) ===`);
  tasksByStage[stage.name].forEach(task => {
    console.log(`  - ${task.title}`);
  });
});

---

Tag-Based Filtering UI

const tags = await callTool('list_tags', { projectId: 230954 });

// Display tag palette
console.log('Filter by tags:');
tags.items.forEach(tag => {
  console.log(`  [ ] #${tag.name}`);
});

// User selects tags: ['backend', 'urgent']
const selectedTags = tags.items
  .filter(t => ['backend', 'urgent'].includes(t.name))
  .map(t => t.tagId);

// Query tasks with selected tags
const filtered = await callTool('search_work_items', {
  projectId: 230954,
  tags: selectedTags
});

---

Assign Task Based on Role

const users = await callTool('list_users', { projectId: 230954 });

// Find all developers
const developers = users.items.filter(u => u.role === 'Developer');

// Round-robin assignment
let currentDev = 0;

for (const taskId of newTaskIds) {
  await callTool('update_work_items', {
    items: [{
      workItemId: taskId,
      assignedUserIds: [developers[currentDev].userId]
    }]
  });

  currentDev = (currentDev + 1) % developers.length;
}

---

Caching

Metadata is automatically cached for 5 minutes to reduce API calls:

• Stages, categories, importance levels change rarely
• Tags may change more frequently (auto-create)
• Users updated when permissions change

Cache invalidation:

// Clear metadata cache
await callTool('clear_cache', {
  pattern: '/metadata'
});

// Re-fetch after cache clear
const freshTags = await callTool('list_tags', { projectId: 230954 });

---

Best Practices

1. Cache Metadata Locally

In UI applications:

// Cache metadata in app state/store
const metadata = {
  stages: await callTool('list_stages', { projectId }),
  categories: await callTool('list_categories', { projectId }),
  tags: await callTool('list_tags', { projectId }),
  users: await callTool('list_users', { projectId })
};

// Refresh periodically (e.g., every 5 minutes)
setInterval(() => {
  metadata.tags = await callTool('list_tags', { projectId });
}, 5 * 60 * 1000);

2. Use Name Resolution

Prefer names for readability:

// ✅ Good - readable
await callTool('create_work_items', {
  items: [{
    title: 'Fix login bug',
    categoryId: 'bug',
    importanceLevelId: 'urgent'
  }]
});

// ❌ Bad - magic numbers
await callTool('create_work_items', {
  items: [{
    title: 'Fix login bug',
    categoryId: 5,
    importanceLevelId: 1
  }]
});

3. Handle Auto-Created Tags

const result = await callTool('update_work_items', {
  items: [{
    workItemId: 123,
    tagIds: ['existing', 'new-tag']
  }]
});

if (result.warnings.length > 0) {
  console.log('Auto-created tags:');
  result.warnings.forEach(w => console.log(`  - ${w}`));

  // Refresh tag list to include new tags
  const updatedTags = await callTool('list_tags', { projectId: 230954 });
}

---

See Also:

• Work Items - Using metadata in work item operations
• Batch Operations - Search with metadata filters
• Array-Based API - Name resolution in batch operations