Migration Guide: MCP Server to MCP-AQL Adapter

// 12 separate tools registered
tools: [
  { name: "create_repo", ... },
  { name: "fork_repo", ... },
  { name: "list_repos", ... },
  { name: "get_repo", ... },
  { name: "search_repos", ... },
  { name: "get_readme", ... },
  { name: "update_repo", ... },
  { name: "transfer_repo", ... },
  { name: "delete_repo", ... },
  { name: "archive_repo", ... },
  { name: "star_repo", ... },
  { name: "unstar_repo", ... },
]

const OPERATION_ROUTES = {
  // CREATE - additive
  create_repo:  { endpoint: "CREATE" },
  fork_repo:    { endpoint: "CREATE" },
  star_repo:    { endpoint: "CREATE" },

  // READ - safe, read-only
  list_repos:   { endpoint: "READ" },
  get_repo:     { endpoint: "READ" },
  search_repos: { endpoint: "READ" },
  get_readme:   { endpoint: "READ" },
  introspect:   { endpoint: "READ" },

  // UPDATE - modifying
  update_repo:   { endpoint: "UPDATE" },
  transfer_repo: { endpoint: "UPDATE" },
  archive_repo:  { endpoint: "UPDATE" },

  // DELETE - destructive
  delete_repo: { endpoint: "DELETE" },
  unstar_repo: { endpoint: "DELETE" },
};

// Old: Each tool has its own handler
server.setRequestHandler("tools/call", async (request) => {
  switch (request.params.name) {
    case "create_repo":
      return handleCreateRepo(request.params.arguments);
    case "list_repos":
      return handleListRepos(request.params.arguments);
    // ... 10 more cases
  }
});

// New: Single router dispatches to handlers
server.setRequestHandler("tools/call", async (request) => {
  const { name: toolName, arguments: args } = request.params;
  const endpoint = toolName.replace("mcp_aql_", "").toUpperCase();
  const { operation, params } = args;

  // Validate routing
  const route = OPERATION_ROUTES[operation];
  if (!route) {
    return formatError(`Unknown operation: ${operation}`);
  }
  if (route.endpoint !== endpoint) {
    return formatError(
      `Operation '${operation}' must be called via mcp_aql_${route.endpoint.toLowerCase()}`
    );
  }

  // Dispatch to existing handler (unchanged!)
  return handlers[operation](params);
});

// This function is identical before and after migration
async function handleCreateRepo(params: {
  name: string;
  private?: boolean;
  description?: string;
}) {
  const repo = await github.createRepo(params);
  return { success: true, data: repo };
}

function handleIntrospect(params: { query: string; name?: string }) {
  if (params.query === "operations") {
    if (params.name) {
      const op = OPERATION_ROUTES[params.name];
      return {
        success: true,
        data: { operation: op ? formatOperation(params.name, op) : null },
      };
    }
    return {
      success: true,
      data: {
        operations: Object.entries(OPERATION_ROUTES).map(
          ([name, route]) => formatOperation(name, route)
        ),
      },
    };
  }

  if (params.query === "types") {
    return { success: true, data: { types: getTypeDefinitions() } };
  }

  return { success: false, error: `Unknown query: ${params.query}` };
}

function formatOperation(name: string, route: OperationRoute) {
  return {
    name,
    endpoint: route.endpoint,
    description: route.description,
    parameters: route.parameters?.map((p) => ({
      name: p.name,
      type: p.type,
      required: p.required ?? false,
      description: p.description,
    })),
  };
}

## Migration Validation

### Tool Registration
- [ ] Old individual tools are removed
- [ ] 5 CRUDE endpoints registered (or fewer if not all are needed)
- [ ] Tool descriptions are clear and endpoint-specific

### Operation Routing
- [ ] Every former tool maps to exactly one CRUDE endpoint
- [ ] Operations are rejected on wrong endpoints
- [ ] Unknown operations return clear error messages

### Introspection
- [ ] `introspect` operation works via mcp_aql_read
- [ ] All operations are discoverable
- [ ] Operation details include parameters and descriptions

### Response Format
- [ ] All responses use `{ success: true, data }` or `{ success: false, error }`
- [ ] No raw exceptions leak to clients

### Backwards Compatibility
- [ ] All functionality from original tools is preserved
- [ ] Parameter names follow snake_case convention
- [ ] Response data structures are unchanged

### Token Reduction
- [ ] Tool count reduced from N to 5 (or fewer)
- [ ] Estimated token savings calculated