Semantic Pen MCP Server

Instructions

Implementation Reference

• src/index.ts:440-496 (handler)

  The core handler function that implements the search_projects tool logic. It fetches all projects via API, filters by partial case-insensitive match on project_name, deduplicates by project_id while counting articles, and formats a markdown response with matching projects.

  private async searchProjects(projectName: string) {
    const result = await this.makeRequest<ProjectQueueResponse>('/article-queue');
    
    if (result.success && result.data) {
      const allProjects = result.data.data.projects;
      const matchingProjects = allProjects.filter(project => 
        project.project_name.toLowerCase().includes(projectName.toLowerCase())
      );
  
      if (matchingProjects.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No projects found matching "${projectName}"`
            }
          ]
        };
      }
  
      // Group by project_id to show unique projects
      const uniqueProjects = matchingProjects.reduce((acc: { [key: string]: Project & { articles: string[] } }, project) => {
        if (!acc[project.project_id]) {
          acc[project.project_id] = {
            ...project,
            articles: [project.extra_data.targetArticleTopic]
          };
        } else {
          acc[project.project_id].articles.push(project.extra_data.targetArticleTopic);
        }
        return acc;
      }, {});
  
      const projectList = Object.values(uniqueProjects).map(project => 
        `📁 **${project.project_name}**\n   Project ID: ${project.project_id}\n   Articles: ${project.articles.length}\n   Latest: ${project.articles[0]}\n   Created: ${new Date(project.created_at).toLocaleDateString()}`
      ).join('\n\n');
  
      return {
        content: [
          {
            type: "text",
            text: `🔍 **Projects matching "${projectName}"** (${Object.keys(uniqueProjects).length} found)\n\n${projectList}`
          }
        ]
      };
    } else {
      return {
        content: [
          {
            type: "text",
            text: `❌ Failed to search projects: ${result.error}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:217-230 (registration)

  Tool registration in the ListTools response, defining the name, description, and input schema for search_projects.

  {
    name: "search_projects",
    description: "Search projects by name",
    inputSchema: {
      type: "object",
      properties: {
        projectName: {
          type: "string",
          description: "The project name to search for (partial match)"
        }
      },
      required: ["projectName"]
    }
  },

• src/index.ts:220-229 (schema)

  Input schema specifying that search_projects requires a 'projectName' string parameter with partial match description.

  inputSchema: {
    type: "object",
    properties: {
      projectName: {
        type: "string",
        description: "The project name to search for (partial match)"
      }
    },
    required: ["projectName"]
  }

• src/index.ts:302-307 (registration)

  Dispatcher in CallToolRequestSchema handler that validates the projectName argument and invokes the searchProjects handler method.

  case "search_projects": {
    if (!args || typeof args !== 'object' || !('projectName' in args) || typeof args.projectName !== 'string') {
      throw new Error("projectName is required and must be a string");
    }
    return await this.searchProjects(args.projectName);
  }