Project Management"
published: false
description: "How I built a complete TypeScript MCP server that transforms any AI assistant into a powerful Jira project manager with 20+ tools, universal field detection, and Czech localization support."
tags: mcp, jira, typescript, ai, projectmanagement, productivity
cover_image:
The Problem That Started It All
As a developer using Claude daily and managing projects in Jira, I was frustrated by the constant context switching. I wanted to:
- Create and manage tickets through natural conversation
- Search for issues without opening another tab
- Handle sprint planning directly in chat
- Upload screenshots and attachments seamlessly
- Work with Czech-localized Jira (my team's setup)
The existing Jira MCP servers were basic - usually just reading tickets or creating simple issues. I needed something comprehensive.
What I Built: 20+ Tools for Complete Project Management
📋 Issue Management (12 tools)
// Core CRUD operations
- create_issue // Smart field detection
- get_issue // Detailed issue info
- update_issue // Flexible field updates
- search_issues // Advanced JQL queries
- delete_issue // Safe deletion
- transition_issue // Status changes
// Advanced operations
- link_issues // Create relationships
- create_task_for_epic // Epic breakdown
- batch_create_issues // Bulk operations
- get_available_fields // Dynamic field discovery
- diagnose_fields // Configuration debugging
- get_create_meta // Project capabilities
💬 Comments & History (3 tools)
- add_comment // Rich text support
- get_comments // Threaded conversations
- get_issue_history // Complete audit trail
📎 Attachments (2 tools)
- upload_attachment // File handling
- download_attachment // Retrieve files
🏃 Sprint & Agile (4 tools)
- get_sprints // Board sprint list
- create_sprint // Sprint setup
- start_sprint // Sprint activation
- complete_sprint // Sprint closure
The Technical Challenges I Solved
1. Universal Field Detection
Every Jira instance is different. Custom fields, different configurations, localized names. I built a dynamic field detection system:
async function getFieldMappings(projectKey: string, issueType: string) {
const createMeta = await jiraClient.getCreateMeta(projectKey, issueType);
// Auto-discover field mappings
const fieldMap = {};
for (const field of createMeta.projects[0].issuetypes[0].fields) {
// Handle different field types and localized names
if (field.name.toLowerCase().includes('story point') ||
field.name.toLowerCase().includes('story points') ||
field.name.toLowerCase().includes('bodování příběhu')) {
fieldMap.storyPoints = field.key;
}
// ... more mappings
}
return fieldMap;
}
This means the server works with any Jira configuration out of the box.
2. Smart Date Parsing
Users want to say "tomorrow" or "next week", not "2024-12-26". I built a comprehensive date parser:
export function parseDate(input: string): string | null {
const now = new Date();
// Handle relative dates
if (input.toLowerCase() === 'tomorrow') {
const tomorrow = new Date(now);
tomorrow.setDate(now.getDate() + 1);
return tomorrow.toISOString().split('T')[0];
}
// Handle "+7d" format
const relativeMatch = input.match(/^([+-]?\d+)([dwmy])$/);
if (relativeMatch) {
const [, amount, unit] = relativeMatch;
const date = new Date(now);
switch (unit) {
case 'd': date.setDate(now.getDate() + parseInt(amount)); break;
case 'w': date.setDate(now.getDate() + parseInt(amount) * 7); break;
// ... more units
}
return date.toISOString().split('T')[0];
}
// Handle European format "31.12.2024"
const europeanMatch = input.match(/^(\d{1,2})\.(\d{1,2})\.(\d{4})$/);
if (europeanMatch) {
const [, day, month, year] = europeanMatch;
return `${year}-${month.padStart(2, '0')}-${day.padStart(2, '0')}`;
}
// ... more formats
}
3. Czech Localization Support
My team uses Czech Jira, so I built comprehensive localization:
const CZECH_FIELD_MAPPINGS = {
'Typ problému': 'Issue Type',
'Přiřazený': 'Assignee',
'Popis': 'Description',
'Úkol': 'Task',
'Chyba': 'Bug',
'Příběh': 'Story',
// ... comprehensive mappings
};
function normalizeFieldName(name: string): string {
return CZECH_FIELD_MAPPINGS[name] || name;
}
This makes the server work seamlessly with localized Jira instances.
4. Professional Error Handling
Nothing's worse than cryptic error messages. I built contextual error handling:
try {
const issue = await jiraClient.createIssue(issueData);
return { success: true, issue };
} catch (error) {
if (error.status === 400) {
const fieldErrors = error.response?.data?.errors;
if (fieldErrors) {
const suggestions = Object.entries(fieldErrors)
.map(([field, message]) => `${field}: ${message}`)
.join('\n');
return {
success: false,
error: `Field validation failed:\n${suggestions}\n\nTip: Use 'get_available_fields' to see valid options.`
};
}
}
return {
success: false,
error: `Failed to create issue: ${error.message}`
};
}
Users get actionable error messages that help them fix issues quickly.
Real-World Usage Examples
Here's how it transforms project management:
Sprint Planning
User: "Create a new sprint for Q1 2025 and add all unassigned story tickets from the backlog"
AI: *Creates sprint, searches for unassigned stories, adds them to sprint*
"Created sprint 'Q1 2025 Sprint 1' and added 8 story tickets. Ready to start when you are!"
Bug Triage
User: "Show me all critical bugs assigned to me that are due this week, then create a summary comment on each"
AI: *Searches with complex JQL, lists bugs, adds summary comments*
"Found 3 critical bugs due this week. Added triage summary to each ticket."
Epic Breakdown
User: "For the User Authentication epic, create tasks for: login form, password reset, and 2FA integration"
AI: *Creates 3 linked tasks under the epic*
"Created 3 tasks under USER-AUTH epic:
- USER-142: Implement login form UI
- USER-143: Build password reset flow
- USER-144: Add 2FA integration"
Architecture Decisions
MCP Tool Design
Each tool is designed for a specific purpose rather than creating generic "do everything" tools:
// ✅ Good: Specific, focused tools
const CreateIssueSchema = z.object({
project: z.string(),
summary: z.string(),
description: "z.string().optional(),"
issueType: z.string(),
// ... specific fields
});
// ❌ Bad: Generic "do anything" tool
const JiraActionSchema = z.object({
action: z.enum(['create', 'update', 'delete', '...']),
data: z.any() // Too generic!
});
This makes the tools more reliable and easier for AI assistants to use correctly.
TypeScript-First Development
Every API response, every tool parameter, every internal function is properly typed:
interface JiraIssue {
key: string;
id: string;
fields: {
summary: string;
description?: string;
status: {
name: string;
statusCategory: {
key: string;
};
};
assignee?: {
displayName: string;
emailAddress: string;
};
// ... complete typing
};
}
This prevents runtime errors and makes the codebase maintainable.
Performance Optimizations
Intelligent Caching
class JiraClient {
private fieldCache = new Map<string, any>();
async getFieldMappings(project: string, issueType: string) {
const cacheKey = `${project}:${issueType}`;
if (this.fieldCache.has(cacheKey)) {
return this.fieldCache.get(cacheKey);
}
const mappings = await this.fetchFieldMappings(project, issueType);
this.fieldCache.set(cacheKey, mappings);
return mappings;
}
}
Batch Operations
Instead of creating issues one-by-one:
async function batchCreateIssues(issues: CreateIssueRequest[]) {
// Process in chunks of 10 for optimal performance
const chunks = chunk(issues, 10);
const results = [];
for (const chunk of chunks) {
const chunkResults = await Promise.all(
chunk.map(issue => this.createSingleIssue(issue))
);
results.push(...chunkResults);
}
return results;
}
Setup Experience
I wanted the setup to be professional but simple:
npm run setup # Interactive configuration wizard
The setup script:
- Validates Jira connection
- Tests API permissions
- Discovers available projects
- Sets up environment variables
- Validates field mappings
Everything's automated but transparent.
What's Next
Short-term additions:
- Dashboard/reporting tools
- Webhook support for real-time updates
- More advanced JQL query builders
Long-term vision:
- Confluence integration
- Custom field plugin system
- Multi-instance support
Lessons Learned
1. Start with User Experience
I began by writing down real conversations I wanted to have with my AI assistant, then built the tools to support those workflows.
2. Embrace Configuration Complexity
Rather than assuming a "standard" Jira setup, I built systems to discover and adapt to any configuration.
3. Error Messages Are User Interface
Spending time on clear, actionable error messages saves users hours of frustration.
4. TypeScript Pays Off
The upfront investment in proper typing prevented countless runtime bugs and made refactoring safe.
5. Test with Real Data
I tested with multiple Jira instances - English, Czech, different configurations. Real-world testing revealed edge cases I never would have anticipated.
Community Impact
Since publishing, the server has been added to multiple MCP directories:
- LinkedIn: Tomáš Gregorovič
Tags: #MCP #Jira #TypeScript #AI #ProjectManagement #Productivity #OpenSource
SOCIAL SHARE CARD GENERATOR