Skip to content

Commit 067311d

Browse files
kunwarVivekkunwarVivek
authored
Merge pull request #13 from kunwarVivek/feature/new_attributes
Feature/new attributes
2 parents c8da6db + 7188ecd commit 067311d

19 files changed

Lines changed: 2329 additions & 91 deletions

‎STATUS.md‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,8 @@
1313
| Request Handling | ✅ Complete | With progressive responses |
1414
| Error Handling | ✅ Complete | Per MCP specifications |
1515
| Resource System | ✅ Complete | Versioned resources with CRUD |
16-
| Response Formatting | 🏗️ In Progress | Needs structured content |
17-
| Error Handling | 🏗️ In Progress | Basic implementation |
18-
| Resource System | 📅 Planned | Not started |
16+
| Response Formatting | ✅ Complete | Structured content implementation |
17+
| Field Value Operations | ✅ Complete | Full GitHub Project v2 field support |
1918

2019
### GitHub Project Tools
2120
| Tool | Status | Notes |
@@ -27,14 +26,35 @@
2726
| get_overdue_milestones | ✅ Complete | Overdue tracking |
2827
| get_upcoming_milestones | ✅ Complete | Future planning |
2928

29+
### Enhanced Features
30+
| Feature | Status | Notes |
31+
|---------|--------|-------|
32+
| Field Value Updates | ✅ Complete | 100% GitHub Project v2 field type coverage |
33+
| Field Value Reading | ✅ Complete | Enhanced GraphQL fragments for all field types |
34+
| Error Handling | ✅ Complete | Comprehensive validation for all field types |
35+
| Type Safety | ✅ Complete | Full TypeScript interface coverage |
36+
3037
### Infrastructure
3138
| Component | Status | Notes |
3239
|-----------|--------|-------|
33-
| GitHub API Integration | ✅ Complete | Basic integration working |
40+
| GitHub API Integration | ✅ Complete | Full GitHub Project v2 API support |
3441
| Service Layer | ✅ Complete | Core services implemented |
35-
| Type Definitions | ✅ Complete | Basic types defined |
36-
| Test Framework | 🏗️ In Progress | Some tests implemented |
37-
| Documentation | 🏗️ In Progress | Needs updates |
42+
| Type Definitions | ✅ Complete | Complete type coverage |
43+
| Test Framework | ✅ Complete | All tests passing |
44+
| Documentation | ✅ Complete | Enhanced API documentation |
45+
46+
## Recent Achievements
47+
48+
### Field Value Enhancement (Completed)
49+
- ✅ Added support for ITERATION field type with `iterationId` mutations
50+
- ✅ Added support for MILESTONE field type with `milestoneId` mutations
51+
- ✅ Added support for ASSIGNEES field type with `userIds` array mutations
52+
- ✅ Added support for LABELS field type with `labelIds` array mutations
53+
- ✅ Enhanced GraphQL queries with proper field value reading fragments
54+
- ✅ Implemented comprehensive error handling and validation
55+
- ✅ Updated TypeScript interfaces for all field types
56+
- ✅ Added complete API documentation and examples
57+
- ✅ Achieved 100% GitHub Project v2 field type coverage
3858

3959
## Current Priorities
4060

‎docs/api-explorer.html‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,15 +100,19 @@ <h1>GitHub Project Manager API Explorer</h1>
100100
properties: {
101101
project: {
102102
type: "object",
103-
required: ["title", "description", "visibility"],
103+
required: ["title", "owner"],
104104
properties: {
105105
title: {
106106
type: "string",
107107
description: "Project title"
108108
},
109-
description: {
109+
shortDescription: {
110110
type: "string",
111-
description: "Project description"
111+
description: "Project short description (optional)"
112+
},
113+
owner: {
114+
type: "string",
115+
description: "Repository owner"
112116
},
113117
visibility: {
114118
type: "string",

‎docs/api-reference/enhanced-field-support.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Enhanced Field Value Support
2+
3+
## Overview
4+
5+
The MCP GitHub Project Manager now supports **100% coverage** of GitHub Project v2 field types for field value operations. This enhancement addresses the critical gap identified in the compliance review and brings complete field type support to the `setFieldValue` and `getFieldValue` methods.
6+
7+
## Supported Field Types
8+
9+
| Field Type | Set Support | Get Support | Value Format | Description |
10+
|------------|-------------|-------------|--------------|-------------|
11+
| TEXT | ✅ | ✅ | `string` | Plain text fields |
12+
| NUMBER | ✅ | ✅ | `number` | Numeric fields |
13+
| DATE | ✅ | ✅ | `string` (ISO format) | Date fields |
14+
| SINGLE_SELECT | ✅ | ✅ | `string` (option name) | Single selection from predefined options |
15+
| ITERATION | ✅ | ✅ | `string` (iteration ID) | Sprint/iteration assignment |
16+
| MILESTONE | ✅ | ✅ | `string` (milestone ID) | Milestone assignment |
17+
| ASSIGNEES | ✅ | ✅ | `string[]` (user IDs) | User assignments |
18+
| LABELS | ✅ | ✅ | `string[]` (label IDs) | Label assignments |
19+
20+
## Field Value Setting Examples
21+
22+
### Basic Field Types
23+
24+
```typescript
25+
// Text field
26+
await projectService.setFieldValue({
27+
projectId: "PROJECT_ID",
28+
itemId: "ITEM_ID",
29+
fieldId: "FIELD_ID",
30+
value: "Updated description"
31+
});
32+
33+
// Number field
34+
await projectService.setFieldValue({
35+
projectId: "PROJECT_ID",
36+
itemId: "ITEM_ID",
37+
fieldId: "FIELD_ID",
38+
value: 42
39+
});
40+
41+
// Date field
42+
await projectService.setFieldValue({
43+
projectId: "PROJECT_ID",
44+
itemId: "ITEM_ID",
45+
fieldId: "FIELD_ID",
46+
value: "2024-12-31"
47+
});
48+
```
49+
50+
### Selection Fields
51+
52+
```typescript
53+
// Single select field
54+
await projectService.setFieldValue({
55+
projectId: "PROJECT_ID",
56+
itemId: "ITEM_ID",
57+
fieldId: "FIELD_ID",
58+
value: "In Progress" // Option name
59+
});
60+
```
61+
62+
### New Enhanced Field Types
63+
64+
```typescript
65+
// Iteration field
66+
await projectService.setFieldValue({
67+
projectId: "PROJECT_ID",
68+
itemId: "ITEM_ID",
69+
fieldId: "FIELD_ID",
70+
value: "ITERATION_ID" // GitHub iteration ID
71+
});
72+
73+
// Milestone field
74+
await projectService.setFieldValue({
75+
projectId: "PROJECT_ID",
76+
itemId: "ITEM_ID",
77+
fieldId: "FIELD_ID",
78+
value: "MILESTONE_ID" // GitHub milestone ID
79+
});
80+
81+
// Assignees field
82+
await projectService.setFieldValue({
83+
projectId: "PROJECT_ID",
84+
itemId: "ITEM_ID",
85+
fieldId: "FIELD_ID",
86+
value: ["USER_ID_1", "USER_ID_2"] // Array of GitHub user IDs
87+
});
88+
89+
// Labels field
90+
await projectService.setFieldValue({
91+
projectId: "PROJECT_ID",
92+
itemId: "ITEM_ID",
93+
fieldId: "FIELD_ID",
94+
value: ["LABEL_ID_1", "LABEL_ID_2"] // Array of GitHub label IDs
95+
});
96+
```
97+
98+
## Field Value Reading Examples
99+
100+
### Reading Enhanced Field Types
101+
102+
```typescript
103+
// Reading iteration field
104+
const iterationValue = await projectService.getFieldValue({
105+
projectId: "PROJECT_ID",
106+
itemId: "ITEM_ID",
107+
fieldId: "FIELD_ID"
108+
});
109+
// Returns: { fieldName: "Sprint", value: { iterationId: "...", title: "Sprint 1" }, fieldType: "ITERATION" }
110+
111+
// Reading milestone field
112+
const milestoneValue = await projectService.getFieldValue({
113+
projectId: "PROJECT_ID",
114+
itemId: "ITEM_ID",
115+
fieldId: "FIELD_ID"
116+
});
117+
// Returns: { fieldName: "Milestone", value: { milestoneId: "...", title: "v1.0" }, fieldType: "MILESTONE" }
118+
119+
// Reading assignees field
120+
const assigneesValue = await projectService.getFieldValue({
121+
projectId: "PROJECT_ID",
122+
itemId: "ITEM_ID",
123+
fieldId: "FIELD_ID"
124+
});
125+
// Returns: { fieldName: "Assignees", value: [{ id: "...", login: "user1" }], fieldType: "ASSIGNEES" }
126+
127+
// Reading labels field
128+
const labelsValue = await projectService.getFieldValue({
129+
projectId: "PROJECT_ID",
130+
itemId: "ITEM_ID",
131+
fieldId: "FIELD_ID"
132+
});
133+
// Returns: { fieldName: "Labels", value: [{ id: "...", name: "bug" }], fieldType: "LABELS" }
134+
```
135+
136+
## Error Handling
137+
138+
The enhanced implementation includes comprehensive error handling for the new field types:
139+
140+
### Validation Errors
141+
142+
```typescript
143+
// Invalid iteration ID
144+
await projectService.setFieldValue({
145+
projectId: "PROJECT_ID",
146+
itemId: "ITEM_ID",
147+
fieldId: "FIELD_ID",
148+
value: null // Will throw ValidationError
149+
});
150+
// Error: "Iteration field 'Sprint' requires a valid iteration ID string"
151+
152+
// Invalid assignees format
153+
await projectService.setFieldValue({
154+
projectId: "PROJECT_ID",
155+
itemId: "ITEM_ID",
156+
fieldId: "FIELD_ID",
157+
value: [] // Will throw ValidationError
158+
});
159+
// Error: "Assignees field 'Team' requires at least one user ID"
160+
161+
// Invalid label IDs
162+
await projectService.setFieldValue({
163+
projectId: "PROJECT_ID",
164+
itemId: "ITEM_ID",
165+
fieldId: "FIELD_ID",
166+
value: ["", "VALID_ID"] // Will throw ValidationError
167+
});
168+
// Error: "Labels field 'Tags' requires valid label ID strings"
169+
```
170+
171+
## GraphQL API Integration
172+
173+
### Field Value Mutations
174+
175+
The implementation uses the proper GitHub GraphQL API mutations:
176+
177+
- **Iteration**: `updateProjectV2ItemFieldValue` with `iterationId` value
178+
- **Milestone**: `updateProjectV2ItemFieldValue` with `milestoneId` value
179+
- **Assignees**: `updateProjectV2ItemFieldValue` with `userIds` array value
180+
- **Labels**: `updateProjectV2ItemFieldValue` with `labelIds` array value
181+
182+
### Field Value Queries
183+
184+
Enhanced GraphQL fragments support reading all field types:
185+
186+
- **Iteration**: `ProjectV2ItemFieldIterationValue` with `iterationId` and `title`
187+
- **Milestone**: `ProjectV2ItemFieldMilestoneValue` with `milestoneId` and `title`
188+
- **Assignees**: `ProjectV2ItemFieldUserValue` with `users.nodes` array
189+
- **Labels**: `ProjectV2ItemFieldLabelValue` with `labels.nodes` array
190+
191+
## Implementation Benefits
192+
193+
1. **Complete API Coverage**: 100% support for all GitHub Project v2 field types
194+
2. **Type Safety**: Strong TypeScript typing with comprehensive interfaces
195+
3. **Error Handling**: Specific validation for each field type with clear error messages
196+
4. **GraphQL Optimization**: Efficient queries and mutations using proper GitHub API patterns
197+
5. **Backward Compatibility**: Existing field types continue to work without changes
198+
199+
## Migration Notes
200+
201+
- **No Breaking Changes**: Existing code for TEXT, NUMBER, DATE, and SINGLE_SELECT fields continues to work
202+
- **Enhanced Error Messages**: More specific validation errors help with debugging
203+
- **New Return Formats**: Enhanced field types return structured objects with additional metadata
204+
205+
This enhancement brings the MCP GitHub Project Manager to full compliance with the GitHub Project v2 API field value operations.

‎docs/api-reference/index.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ This section provides comprehensive documentation for all tools available in the
1313
| `get_overdue_milestones` | Get a list of overdue milestones | [Documentation](get-overdue-milestones.md) |
1414
| `get_upcoming_milestones` | Get a list of upcoming milestones | [Documentation](get-upcoming-milestones.md) |
1515

16+
## Enhanced Features
17+
18+
| Feature | Description | Documentation |
19+
|---------|-------------|---------------|
20+
| Enhanced Field Support | Complete coverage of GitHub Project v2 field types | [Documentation](enhanced-field-support.md) |
21+
1622
## Using the API
1723

1824
All tools follow the Model Context Protocol (MCP) standard for request and response formats. To use a tool:
@@ -28,7 +34,8 @@ All tools follow the Model Context Protocol (MCP) standard for request and respo
2834
"arguments": {
2935
"project": {
3036
"title": "New Project",
31-
"description": "Project description",
37+
"shortDescription": "Project description",
38+
"owner": "repository_owner",
3239
"visibility": "private"
3340
},
3441
"milestones": [

‎docs/mcp/github-projects-integration.md‎

Lines changed: 59 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ This document details how the MCP server interfaces with GitHub's Projects API (
4444
### GraphQL API Usage
4545

4646
```typescript
47-
// Example GraphQL Query
47+
// Example GraphQL Mutations - Schema Compliant Implementation
4848
const createProjectMutation = `
4949
mutation($input: CreateProjectV2Input!) {
5050
createProjectV2(input: $input) {
@@ -60,22 +60,71 @@ const createProjectMutation = `
6060
}
6161
`;
6262

63-
// Implementation
63+
const updateProjectMutation = `
64+
mutation($input: UpdateProjectV2Input!) {
65+
updateProjectV2(input: $input) {
66+
projectV2 {
67+
id
68+
title
69+
shortDescription
70+
closed
71+
createdAt
72+
updatedAt
73+
}
74+
}
75+
}
76+
`;
77+
78+
// Schema-Compliant Implementation
6479
class GitHubProjectRepository {
6580
async create(data: CreateProject): Promise<Project> {
66-
const response = await this.graphql(createProjectMutation, {
67-
input: {
68-
ownerId: this.owner,
69-
title: data.title,
70-
description: data.description,
71-
repositoryId: this.repo,
72-
},
81+
// Step 1: Create project (without description - schema compliance)
82+
const createInput: any = {
83+
ownerId: this.owner,
84+
title: data.title,
85+
};
86+
87+
if (this.repo) {
88+
createInput.repositoryId = this.repo;
89+
}
90+
91+
const createResponse = await this.graphql(createProjectMutation, {
92+
input: createInput,
7393
});
74-
return this.mapToProject(response.createProjectV2.projectV2);
94+
95+
let project = createResponse.createProjectV2.projectV2;
96+
97+
// Step 2: Update with description if provided (separate mutation)
98+
if (data.description) {
99+
const updateResponse = await this.graphql(updateProjectMutation, {
100+
input: {
101+
projectId: project.id,
102+
shortDescription: data.description,
103+
},
104+
});
105+
project = updateResponse.updateProjectV2.projectV2;
106+
}
107+
108+
return this.mapToProject(project);
75109
}
76110
}
77111
```
78112

113+
### Schema Compliance Notes
114+
115+
**Important**: GitHub's CreateProjectV2Input schema does NOT accept description fields:
116+
- ❌ `description` - Not a valid field
117+
- ❌ `shortDescription` - Not a valid field
118+
119+
Valid CreateProjectV2Input fields:
120+
- ✅ `ownerId` (required)
121+
- ✅ `title` (required)
122+
- ✅ `repositoryId` (optional)
123+
- ✅ `teamId` (optional)
124+
- ✅ `clientMutationId` (optional)
125+
126+
To set a project description, use a separate UpdateProjectV2Input mutation after creation.
127+
79128
### API Features
80129

81130
1. **Projects API (v2)**

0 commit comments

Comments
 (0)