Ontology MCP

Instructions

Implementation Reference

• src/tools/index.ts:50-69 (handler)

  The primary handler function for the 'mcp_sparql_execute_query' tool. It receives arguments, calls SparqlService.executeQuery, formats the result as JSON/text, and returns a ToolResponse or error message.

  async handler(args: ExecuteQueryArgs): Promise<ToolResponse> {
    try {
      const result = await sparqlService.executeQuery(args.query, args.repository, args.format);
      
      // 결과를 서식화하여 반환
      return {
        content: [{
          type: 'text',
          text: typeof result === 'object' ? JSON.stringify(result, null, 2) : result.toString()
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `쿼리 실행 오류: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }

• src/tools/index.ts:23-49 (schema)

  The JSON schema defining the input parameters for the tool, including required 'query' and optional fields like repository, endpoint, format, and explain.

  inputSchema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '실행할 SPARQL 쿼리'
      },
      repository: {
        type: 'string',
        description: '쿼리를 실행할 리포지토리 이름'
      },
      endpoint: {
        type: 'string',
        description: 'SPARQL 엔드포인트 URL'
      },
      format: {
        type: 'string',
        enum: ['json', 'xml', 'csv', 'tsv'],
        description: '결과 형식(json, xml, csv, tsv)'
      },
      explain: {
        type: 'boolean',
        description: '쿼리 실행 계획 반환 여부'
      }
    },
    required: ['query']
  },

• src/tools/index.ts:20-70 (registration)

  The complete tool definition object that registers 'mcp_sparql_execute_query' in the exported tools array, used by the MCP server.

  {
    name: 'mcp_sparql_execute_query',
    description: 'SPARQL 쿼리를 실행하고 결과를 반환합니다',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: '실행할 SPARQL 쿼리'
        },
        repository: {
          type: 'string',
          description: '쿼리를 실행할 리포지토리 이름'
        },
        endpoint: {
          type: 'string',
          description: 'SPARQL 엔드포인트 URL'
        },
        format: {
          type: 'string',
          enum: ['json', 'xml', 'csv', 'tsv'],
          description: '결과 형식(json, xml, csv, tsv)'
        },
        explain: {
          type: 'boolean',
          description: '쿼리 실행 계획 반환 여부'
        }
      },
      required: ['query']
    },
    async handler(args: ExecuteQueryArgs): Promise<ToolResponse> {
      try {
        const result = await sparqlService.executeQuery(args.query, args.repository, args.format);
        
        // 결과를 서식화하여 반환
        return {
          content: [{
            type: 'text',
            text: typeof result === 'object' ? JSON.stringify(result, null, 2) : result.toString()
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: 'text',
            text: `쿼리 실행 오류: ${error instanceof Error ? error.message : String(error)}`
          }]
        };
      }
    }
  },

• src/services/sparql-service.ts:17-47 (helper)

  The core SparqlService.executeQuery method that performs the actual HTTP POST request to the SPARQL endpoint to execute the query and parse the response.

  async executeQuery(query: string, repository?: string, format: string = 'json', explain = false): Promise<any> {
    const repo = repository || this.config.defaultRepository;
    const endpoint = this.config.endpoint;
    const url = explain 
      ? `${endpoint}/repositories/${repo}/explain`
      : `${endpoint}/repositories/${repo}`;
    
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/sparql-query',
          'Accept': format === 'json' ? 'application/sparql-results+json' : `application/sparql-results+${format}`
        },
        body: query
      });
  
      if (!response.ok) {
        throw new Error(`SPARQL 쿼리 실행 오류 (${response.status}): ${await response.text()}`);
      }
  
      if (format === 'json') {
        return await response.json();
      } else {
        return await response.text();
      }
    } catch (error) {
      console.error('SPARQL 쿼리 실행 중 오류:', error);
      throw error;
    }
  }

• src/types/index.ts:78-84 (schema)

  TypeScript interface defining the ExecuteQueryArgs type used in the tool handler signature for type safety.

  export interface ExecuteQueryArgs {
    query: string;
    repository?: string;
    endpoint?: string;
    format?: 'json' | 'xml' | 'csv' | 'tsv';
    explain?: boolean;
  }

• src/index.ts:26-26 (registration)

  MCP server capabilities declaration advertising support for the 'mcp_sparql_execute_query' tool.

  mcp_sparql_execute_query: true,