feat: improve MCP server naming and add proper CI testing

beshkenadze · beshkenadze · commit 639c541ef244 · 2025-07-20T17:35:21.000+03:00
- Change server name from eCFRAPIDocumentationServer to eCFRSDKServer
- Add dedicated MCP server test script that verifies actual functionality
- Update CI workflow to use the new test script
- Fix test version assertions
- Better represents the project as an SDK rather than just API documentation
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -48,13 +48,4 @@ jobs:
         run: bun test
 
       - name: Verify MCP server starts
-        run: |
-          timeout 5s bun run mcp:server
-          exit_code=$?
-          if [ $exit_code -eq 124 ]; then
-            echo "MCP server started successfully (timeout expected)"
-            exit 0
-          else
-            echo "MCP server failed to start with exit code: $exit_code"
-            exit 1
-          fi
+        run: bun run scripts/test-mcp-server.ts
diff --git a/docs/v1-openapi3.json b/docs/v1-openapi3.json
@@ -1,7 +1,8 @@
 {
   "openapi": "3.0.0",
   "info": {
-    "title": "eCFR API Documentation",
+    "title": "eCFR SDK",
+    "description": "TypeScript SDK and Model Context Protocol server for the Electronic Code of Federal Regulations (eCFR) API",
     "version": "1.0.0"
   },
   "tags": [
@@ -28,7 +29,9 @@
             "description": "```json\n  {\n    \"agencies\": [\n      {\n        \"name\": \"Administrative Conference of the United States\",\n        \"short_name\": \"ACUS\",\n        \"display_name\": \"Administrative Conference of the United States\",\n        \"sortable_name\": \"Administrative Conference of the United States\",\n        \"slug\": \"administrative-conference-of-the-united-states\",\n        \"children\": [],\n        \"cfr_references\": [\n          {\n            \"title\": 1,\n            \"chapter\": \"III\"\n          }\n        ]\n      },\n  ...\n      {\n        \"name\": \"Department of Agriculture\",\n        \"short_name\": \"USDA\",\n        \"display_name\": \"Department of Agriculture\",\n        \"sortable_name\": \"Agriculture, Department of\",\n        \"slug\": \"agriculture-department\",\n        \"children\": [\n          {\n          \"name\": \"Agricultural Marketing Service\",\n          \"short_name\": \"AMS\",\n          \"display_name\": \"Agricultural Marketing Service, Department of Agriculture\",\n          \"sortable_name\": \"Agricultural Marketing Service\",\n          \"slug\": \"agricultural-marketing-service\",\n          \"cfr_references\": [\n            {\n              \"title\": 7,\n              \"chapter\": \"I\"\n            },\n            ...\n          ],\n        \"cfr_references\": [\n          {\n            \"title\": 2,\n            \"chapter\": \"IV\",\n          },\n          ...\n        ]\n      },\n  ...\n      {\n        \"name\": \"World Agricultural Outlook Board\",\n        \"short_name\": \"WAOB\",\n        \"display_name\": \"World Agricultural Outlook Board\",\n        \"sortable_name\": \"World Agricultural Outlook Board\",\n        \"slug\": \"world-agricultural-outlook-board\",\n        \"cfr_references\": [\n          {\n            \"title\": 7,\n            \"chapter\": \"XXXVIII\"\n          }\n        ]\n      }\n    ]\n  }\n```\n"
           }
         },
-        "tags": ["Admin Service"]
+        "tags": [
+          "Admin Service"
+        ]
       }
     },
     "/api/admin/v1/corrections.json": {
@@ -77,7 +80,9 @@
             "description": "Title not found"
           }
         },
-        "tags": ["Admin Service"]
+        "tags": [
+          "Admin Service"
+        ]
       }
     },
     "/api/admin/v1/corrections/title/{title}.json": {
@@ -103,7 +108,9 @@
             "description": "Response 404"
           }
         },
-        "tags": ["Admin Service"]
+        "tags": [
+          "Admin Service"
+        ]
       }
     },
     "/api/search/v1/results": {
@@ -221,7 +228,10 @@
             "in": "query",
             "schema": {
               "type": "string",
-              "enum": ["date", "results"],
+              "enum": [
+                "date",
+                "results"
+              ],
               "default": "results"
             }
           }
@@ -284,7 +294,9 @@
             "description": "Invalid input"
           }
         },
-        "tags": ["Search Service"]
+        "tags": [
+          "Search Service"
+        ]
       }
     },
     "/api/search/v1/count": {
@@ -367,7 +379,9 @@
             "description": "Invalid input"
           }
         },
-        "tags": ["Search Service"]
+        "tags": [
+          "Search Service"
+        ]
       }
     },
     "/api/search/v1/summary": {
@@ -450,7 +464,9 @@
             "description": "Invalid input"
           }
         },
-        "tags": ["Search Service"]
+        "tags": [
+          "Search Service"
+        ]
       }
     },
     "/api/search/v1/counts/daily": {
@@ -533,7 +549,9 @@
             "description": "Invalid input"
           }
         },
-        "tags": ["Search Service"]
+        "tags": [
+          "Search Service"
+        ]
       }
     },
     "/api/search/v1/counts/titles": {
@@ -616,7 +634,9 @@
             "description": "Invalid input"
           }
         },
-        "tags": ["Search Service"]
+        "tags": [
+          "Search Service"
+        ]
       }
     },
     "/api/search/v1/counts/hierarchy": {
@@ -699,7 +719,9 @@
             "description": "Invalid input"
           }
         },
-        "tags": ["Search Service"]
+        "tags": [
+          "Search Service"
+        ]
       }
     },
     "/api/search/v1/suggestions": {
@@ -782,7 +804,9 @@
             "description": "Invalid input"
           }
         },
-        "tags": ["Search Service"]
+        "tags": [
+          "Search Service"
+        ]
       }
     },
     "/api/versioner/v1/ancestry/{date}/title-{title}.json": {
@@ -874,7 +898,9 @@
             "description": "null // Invalid input or missing some hierarchy"
           }
         },
-        "tags": ["Versioner Service"]
+        "tags": [
+          "Versioner Service"
+        ]
       }
     },
     "/api/versioner/v1/full/{date}/title-{title}.xml": {
@@ -977,7 +1003,9 @@
             "description": "No matching content found."
           }
         },
-        "tags": ["Versioner Service"]
+        "tags": [
+          "Versioner Service"
+        ]
       }
     },
     "/api/versioner/v1/structure/{date}/title-{title}.json": {
@@ -1013,7 +1041,9 @@
             "description": "Invalid input."
           }
         },
-        "tags": ["Versioner Service"]
+        "tags": [
+          "Versioner Service"
+        ]
       }
     },
     "/api/versioner/v1/titles.json": {
@@ -1025,7 +1055,9 @@
             "description": "```json\n  {\n    \"titles\": [\n      {\n        \"number\": 1,\n        \"name\": \"General Provisions\",\n        \"latest_amended_on\": \"2022-05-04\",\n        \"latest_issue_date\": \"2022-05-04\",\n        \"up_to_date_as_of\": \"2022-07-28\",\n        \"reserved\": false\n      },\n      {\n        \"number\": 2,\n        \"name\": \"Federal Financial Assistance\",\n        \"latest_amended_on\": \"2022-05-19\",\n        \"latest_issue_date\": \"2022-06-03\",\n        \"up_to_date_as_of\": \"2022-07-28\",\n        \"reserved\": false,\n        \"processing_in_progress\": true\n      },\n      {\n        \"number\": 3,\n        \"name\": \"The President\",\n        \"latest_amended_on\": \"2015-03-17\",\n        \"latest_issue_date\": \"2019-06-27\",\n        \"up_to_date_as_of\": \"2022-07-28\",\n        \"reserved\": false\n      },\n      ...\n    ],\n    meta\": {\n      \"date\": \"2022-07-29\",\n      \"import_in_progress\": true\n    }\n  }\n```\n"
           }
         },
-        "tags": ["Versioner Service"]
+        "tags": [
+          "Versioner Service"
+        ]
       }
     },
     "/api/versioner/v1/versions/title-{title}.json": {
@@ -1137,7 +1169,9 @@
             "description": "```json\n{\n  \"message\": \"Title 2 currently unavailable\"\n}\n```\n"
           }
         },
-        "tags": ["Versioner Service"]
+        "tags": [
+          "Versioner Service"
+        ]
       }
     }
   },
@@ -1146,4 +1180,4 @@
       "url": "//www.ecfr.gov"
     }
   ]
-}
+}
diff --git a/scripts/fix-and-convert-swagger.ts b/scripts/fix-and-convert-swagger.ts
@@ -93,10 +93,15 @@ async function fixAndConvert() {
       }
     }
 
-    // Ensure all required fields exist
+    // Ensure all required fields exist and set proper title
     if (!swagger2.info) {
       swagger2.info = { title: 'eCFR API', version: '1.0.0' };
     }
+    
+    // Update the title to be more descriptive for SDK generation
+    // Note: Orval appends "Server" to the title for MCP generation, so we use just "eCFR SDK"
+    swagger2.info.title = 'eCFR SDK';
+    swagger2.info.description = swagger2.info.description || 'TypeScript SDK and Model Context Protocol server for the Electronic Code of Federal Regulations (eCFR) API';
 
     console.log('🔄 Converting to OpenAPI 3.0...');
 
diff --git a/scripts/test-mcp-server.ts b/scripts/test-mcp-server.ts
@@ -0,0 +1,81 @@
+#!/usr/bin/env bun
+
+import { spawn } from 'node:child_process';
+
+async function testMCPServer() {
+  console.log('🧪 Testing MCP server...');
+  
+  // Start the MCP server
+  const server = spawn('bun', ['run', 'mcp:server'], {
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+
+  let output = '';
+  let errorOutput = '';
+
+  server.stdout.on('data', (data) => {
+    output += data.toString();
+  });
+
+  server.stderr.on('data', (data) => {
+    errorOutput += data.toString();
+  });
+
+  // Wait for server to start
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  // Send initialize request
+  const initRequest = {
+    jsonrpc: "2.0",
+    method: "initialize",
+    params: {
+      protocolVersion: "0.1.0",
+      capabilities: {},
+      clientInfo: {
+        name: "test-client",
+        version: "1.0.0"
+      }
+    },
+    id: 1
+  };
+
+  server.stdin.write(JSON.stringify(initRequest) + '\n');
+
+  // Wait for response
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  // Check outputs
+  const combinedOutput = output + errorOutput;
+  
+  if (combinedOutput.includes('MCP server running on stdio')) {
+    console.log('✅ MCP server started successfully');
+  }
+  
+  // Try to parse the response
+  const lines = output.split('\n');
+  for (const line of lines) {
+    if (line.trim().startsWith('{')) {
+      try {
+        const response = JSON.parse(line);
+        if (response.result?.serverInfo?.name === 'eCFRSDKServer') {
+          console.log('✅ MCP server responded correctly to initialize request');
+          server.kill();
+          process.exit(0);
+        }
+      } catch (e) {
+        // Continue checking other lines
+      }
+    }
+  }
+
+  console.error('❌ MCP server test failed');
+  console.error('Output:', output);
+  console.error('Error:', errorOutput);
+  server.kill();
+  process.exit(1);
+}
+
+testMCPServer().catch(error => {
+  console.error('❌ Test failed:', error);
+  process.exit(1);
+});
diff --git a/src/integration.simple.test.ts b/src/integration.simple.test.ts
diff --git a/src/mcp/server.test.ts b/src/mcp/server.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,8 @@`
`1`	`1`	`{`
`2`	`2`	`"openapi": "3.0.0",`
`3`	`3`	`"info": {`
`4`		`- "title": "eCFR API Documentation",`
	`4`	`+ "title": "eCFR SDK",`
	`5`	`+ "description": "TypeScript SDK and Model Context Protocol server for the Electronic Code of Federal Regulations (eCFR) API",`
`5`	`6`	`"version": "1.0.0"`
`6`	`7`	`},`
`7`	`8`	`"tags": [`
`@@ -28,7 +29,9 @@`
`28`	`29`	"description": "```json\n {\n \"agencies\": [\n {\n \"name\": \"Administrative Conference of the United States\",\n \"short_name\": \"ACUS\",\n \"display_name\": \"Administrative Conference of the United States\",\n \"sortable_name\": \"Administrative Conference of the United States\",\n \"slug\": \"administrative-conference-of-the-united-states\",\n \"children\": [],\n \"cfr_references\": [\n {\n \"title\": 1,\n \"chapter\": \"III\"\n }\n ]\n },\n ...\n {\n \"name\": \"Department of Agriculture\",\n \"short_name\": \"USDA\",\n \"display_name\": \"Department of Agriculture\",\n \"sortable_name\": \"Agriculture, Department of\",\n \"slug\": \"agriculture-department\",\n \"children\": [\n {\n \"name\": \"Agricultural Marketing Service\",\n \"short_name\": \"AMS\",\n \"display_name\": \"Agricultural Marketing Service, Department of Agriculture\",\n \"sortable_name\": \"Agricultural Marketing Service\",\n \"slug\": \"agricultural-marketing-service\",\n \"cfr_references\": [\n {\n \"title\": 7,\n \"chapter\": \"I\"\n },\n ...\n ],\n \"cfr_references\": [\n {\n \"title\": 2,\n \"chapter\": \"IV\",\n },\n ...\n ]\n },\n ...\n {\n \"name\": \"World Agricultural Outlook Board\",\n \"short_name\": \"WAOB\",\n \"display_name\": \"World Agricultural Outlook Board\",\n \"sortable_name\": \"World Agricultural Outlook Board\",\n \"slug\": \"world-agricultural-outlook-board\",\n \"cfr_references\": [\n {\n \"title\": 7,\n \"chapter\": \"XXXVIII\"\n }\n ]\n }\n ]\n }\n```\n"
`29`	`30`	`}`
`30`	`31`	`},`
`31`		`- "tags": ["Admin Service"]`
	`32`	`+ "tags": [`
	`33`	`+ "Admin Service"`
	`34`	`+ ]`
`32`	`35`	`}`
`33`	`36`	`},`
`34`	`37`	`"/api/admin/v1/corrections.json": {`
`@@ -77,7 +80,9 @@`
`77`	`80`	`"description": "Title not found"`
`78`	`81`	`}`
`79`	`82`	`},`
`80`		`- "tags": ["Admin Service"]`
	`83`	`+ "tags": [`
	`84`	`+ "Admin Service"`
	`85`	`+ ]`
`81`	`86`	`}`
`82`	`87`	`},`
`83`	`88`	`"/api/admin/v1/corrections/title/{title}.json": {`
`@@ -103,7 +108,9 @@`
`103`	`108`	`"description": "Response 404"`
`104`	`109`	`}`
`105`	`110`	`},`
`106`		`- "tags": ["Admin Service"]`
	`111`	`+ "tags": [`
	`112`	`+ "Admin Service"`
	`113`	`+ ]`
`107`	`114`	`}`
`108`	`115`	`},`
`109`	`116`	`"/api/search/v1/results": {`
`@@ -221,7 +228,10 @@`
`221`	`228`	`"in": "query",`
`222`	`229`	`"schema": {`
`223`	`230`	`"type": "string",`
`224`		`- "enum": ["date", "results"],`
	`231`	`+ "enum": [`
	`232`	`+ "date",`
	`233`	`+ "results"`
	`234`	`+ ],`
`225`	`235`	`"default": "results"`
`226`	`236`	`}`
`227`	`237`	`}`
`@@ -284,7 +294,9 @@`
`284`	`294`	`"description": "Invalid input"`
`285`	`295`	`}`
`286`	`296`	`},`
`287`		`- "tags": ["Search Service"]`
	`297`	`+ "tags": [`
	`298`	`+ "Search Service"`
	`299`	`+ ]`
`288`	`300`	`}`
`289`	`301`	`},`
`290`	`302`	`"/api/search/v1/count": {`
`@@ -367,7 +379,9 @@`
`367`	`379`	`"description": "Invalid input"`
`368`	`380`	`}`
`369`	`381`	`},`
`370`		`- "tags": ["Search Service"]`
	`382`	`+ "tags": [`
	`383`	`+ "Search Service"`
	`384`	`+ ]`
`371`	`385`	`}`
`372`	`386`	`},`
`373`	`387`	`"/api/search/v1/summary": {`
`@@ -450,7 +464,9 @@`
`450`	`464`	`"description": "Invalid input"`
`451`	`465`	`}`
`452`	`466`	`},`
`453`		`- "tags": ["Search Service"]`
	`467`	`+ "tags": [`
	`468`	`+ "Search Service"`
	`469`	`+ ]`
`454`	`470`	`}`
`455`	`471`	`},`
`456`	`472`	`"/api/search/v1/counts/daily": {`
`@@ -533,7 +549,9 @@`
`533`	`549`	`"description": "Invalid input"`
`534`	`550`	`}`
`535`	`551`	`},`
`536`		`- "tags": ["Search Service"]`
	`552`	`+ "tags": [`
	`553`	`+ "Search Service"`
	`554`	`+ ]`
`537`	`555`	`}`
`538`	`556`	`},`
`539`	`557`	`"/api/search/v1/counts/titles": {`
`@@ -616,7 +634,9 @@`
`616`	`634`	`"description": "Invalid input"`
`617`	`635`	`}`
`618`	`636`	`},`
`619`		`- "tags": ["Search Service"]`
	`637`	`+ "tags": [`
	`638`	`+ "Search Service"`
	`639`	`+ ]`
`620`	`640`	`}`
`621`	`641`	`},`
`622`	`642`	`"/api/search/v1/counts/hierarchy": {`
`@@ -699,7 +719,9 @@`
`699`	`719`	`"description": "Invalid input"`
`700`	`720`	`}`
`701`	`721`	`},`
`702`		`- "tags": ["Search Service"]`
	`722`	`+ "tags": [`
	`723`	`+ "Search Service"`
	`724`	`+ ]`
`703`	`725`	`}`
`704`	`726`	`},`
`705`	`727`	`"/api/search/v1/suggestions": {`
`@@ -782,7 +804,9 @@`
`782`	`804`	`"description": "Invalid input"`
`783`	`805`	`}`
`784`	`806`	`},`
`785`		`- "tags": ["Search Service"]`
	`807`	`+ "tags": [`
	`808`	`+ "Search Service"`
	`809`	`+ ]`
`786`	`810`	`}`
`787`	`811`	`},`
`788`	`812`	`"/api/versioner/v1/ancestry/{date}/title-{title}.json": {`
`@@ -874,7 +898,9 @@`
`874`	`898`	`"description": "null // Invalid input or missing some hierarchy"`
`875`	`899`	`}`
`876`	`900`	`},`
`877`		`- "tags": ["Versioner Service"]`
	`901`	`+ "tags": [`
	`902`	`+ "Versioner Service"`
	`903`	`+ ]`
`878`	`904`	`}`
`879`	`905`	`},`
`880`	`906`	`"/api/versioner/v1/full/{date}/title-{title}.xml": {`
`@@ -977,7 +1003,9 @@`
`977`	`1003`	`"description": "No matching content found."`
`978`	`1004`	`}`
`979`	`1005`	`},`
`980`		`- "tags": ["Versioner Service"]`
	`1006`	`+ "tags": [`
	`1007`	`+ "Versioner Service"`
	`1008`	`+ ]`
`981`	`1009`	`}`
`982`	`1010`	`},`
`983`	`1011`	`"/api/versioner/v1/structure/{date}/title-{title}.json": {`
`@@ -1013,7 +1041,9 @@`
`1013`	`1041`	`"description": "Invalid input."`
`1014`	`1042`	`}`
`1015`	`1043`	`},`
`1016`		`- "tags": ["Versioner Service"]`
	`1044`	`+ "tags": [`
	`1045`	`+ "Versioner Service"`
	`1046`	`+ ]`
`1017`	`1047`	`}`
`1018`	`1048`	`},`
`1019`	`1049`	`"/api/versioner/v1/titles.json": {`
`@@ -1025,7 +1055,9 @@`
`1025`	`1055`	"description": "```json\n {\n \"titles\": [\n {\n \"number\": 1,\n \"name\": \"General Provisions\",\n \"latest_amended_on\": \"2022-05-04\",\n \"latest_issue_date\": \"2022-05-04\",\n \"up_to_date_as_of\": \"2022-07-28\",\n \"reserved\": false\n },\n {\n \"number\": 2,\n \"name\": \"Federal Financial Assistance\",\n \"latest_amended_on\": \"2022-05-19\",\n \"latest_issue_date\": \"2022-06-03\",\n \"up_to_date_as_of\": \"2022-07-28\",\n \"reserved\": false,\n \"processing_in_progress\": true\n },\n {\n \"number\": 3,\n \"name\": \"The President\",\n \"latest_amended_on\": \"2015-03-17\",\n \"latest_issue_date\": \"2019-06-27\",\n \"up_to_date_as_of\": \"2022-07-28\",\n \"reserved\": false\n },\n ...\n ],\n meta\": {\n \"date\": \"2022-07-29\",\n \"import_in_progress\": true\n }\n }\n```\n"
`1026`	`1056`	`}`
`1027`	`1057`	`},`
`1028`		`- "tags": ["Versioner Service"]`
	`1058`	`+ "tags": [`
	`1059`	`+ "Versioner Service"`
	`1060`	`+ ]`
`1029`	`1061`	`}`
`1030`	`1062`	`},`
`1031`	`1063`	`"/api/versioner/v1/versions/title-{title}.json": {`
`@@ -1137,7 +1169,9 @@`
`1137`	`1169`	"description": "```json\n{\n \"message\": \"Title 2 currently unavailable\"\n}\n```\n"
`1138`	`1170`	`}`
`1139`	`1171`	`},`
`1140`		`- "tags": ["Versioner Service"]`
	`1172`	`+ "tags": [`
	`1173`	`+ "Versioner Service"`
	`1174`	`+ ]`
`1141`	`1175`	`}`
`1142`	`1176`	`}`
`1143`	`1177`	`},`
`@@ -1146,4 +1180,4 @@`
`1146`	`1180`	`"url": "//www.ecfr.gov"`
`1147`	`1181`	`}`
`1148`	`1182`	`]`
`1149`		`-}`
	`1183`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -93,10 +93,15 @@ async function fixAndConvert() {`
`93`	`93`	`}`
`94`	`94`	`}`
`95`	`95`
`96`		`- // Ensure all required fields exist`
	`96`	`+ // Ensure all required fields exist and set proper title`
`97`	`97`	`if (!swagger2.info) {`
`98`	`98`	`swagger2.info = { title: 'eCFR API', version: '1.0.0' };`
`99`	`99`	`}`
	`100`	`+`
	`101`	`+ // Update the title to be more descriptive for SDK generation`
	`102`	`+ // Note: Orval appends "Server" to the title for MCP generation, so we use just "eCFR SDK"`
	`103`	`+ swagger2.info.title = 'eCFR SDK';`
	`104`	`+ swagger2.info.description = swagger2.info.description \|\| 'TypeScript SDK and Model Context Protocol server for the Electronic Code of Federal Regulations (eCFR) API';`
`100`	`105`
`101`	`106`	`console.log('🔄 Converting to OpenAPI 3.0...');`
`102`	`107`