index.ts•20.9 kB
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
Tool,
} from "@modelcontextprotocol/sdk/types.js";
import { readFileSync, readdirSync, existsSync } from "fs";
import { join, dirname } from "path";
import { fileURLToPath } from "url";
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
interface ComponentDoc {
filename: string;
component: string;
content: string;
}
interface RuleDoc {
filename: string;
category: string;
content: string;
}
interface SetupDoc {
filename: string;
setupType: string;
content: string;
}
class ModusDocsServer {
private server: Server;
private docs: ComponentDoc[] = [];
private rules: RuleDoc[] = [];
private setup: SetupDoc[] = [];
private docsPath: string;
private rulesPath: string;
private setupPath: string;
constructor() {
this.server = new Server(
{
name: "mcp-modus",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
// Try to find docs directory - check both dev and production paths
const possibleDocsPaths = [
join(__dirname, "..", "docs"), // Development: dist/../docs
join(__dirname, "docs"), // Production: dist/docs
join(process.cwd(), "docs"), // Current working directory
];
const possibleRulesPaths = [
join(__dirname, "..", "rules"), // Development: dist/../rules
join(__dirname, "rules"), // Production: dist/rules
join(process.cwd(), "rules"), // Current working directory
];
const possibleSetupPaths = [
join(__dirname, "..", "setup"), // Development: dist/../setup
join(__dirname, "setup"), // Production: dist/setup
join(process.cwd(), "setup"), // Current working directory
];
this.docsPath =
possibleDocsPaths.find((p) => existsSync(p)) || possibleDocsPaths[0];
this.rulesPath =
possibleRulesPaths.find((p) => existsSync(p)) || possibleRulesPaths[0];
this.setupPath =
possibleSetupPaths.find((p) => existsSync(p)) || possibleSetupPaths[0];
this.setupHandlers();
this.loadDocs();
this.loadRules();
this.loadSetup();
}
private loadDocs(): void {
if (!existsSync(this.docsPath)) {
console.error(`Documentation directory not found at: ${this.docsPath}`);
console.error("Please run: node download-docs.js");
return;
}
const files = readdirSync(this.docsPath).filter((f) => f.endsWith(".md"));
for (const file of files) {
const content = readFileSync(join(this.docsPath, file), "utf-8");
const component = file.replace("modus-wc-", "").replace(".md", "");
this.docs.push({
filename: file,
component,
content,
});
}
console.error(`Loaded ${this.docs.length} component documentation files`);
}
private loadRules(): void {
if (!existsSync(this.rulesPath)) {
console.error(`Rules directory not found at: ${this.rulesPath}`);
console.error("Please run: node download-docs.js");
return;
}
const files = readdirSync(this.rulesPath).filter((f) => f.endsWith(".md"));
for (const file of files) {
const content = readFileSync(join(this.rulesPath, file), "utf-8");
const category = file.replace(".md", "").replace("modus_", "");
this.rules.push({
filename: file,
category,
content,
});
}
console.error(`Loaded ${this.rules.length} design rules files`);
}
private loadSetup(): void {
if (!existsSync(this.setupPath)) {
console.error(`Setup directory not found at: ${this.setupPath}`);
console.error("Please run: node download-docs.js");
return;
}
const files = readdirSync(this.setupPath).filter((f) => f.endsWith(".md"));
for (const file of files) {
const content = readFileSync(join(this.setupPath, file), "utf-8");
let setupType = file.replace(".md", "").replace("setup_", "");
// Map filenames to more user-friendly types
if (setupType === "universal_rules") setupType = "universal";
if (setupType === "theme_usage") setupType = "theme";
this.setup.push({
filename: file,
setupType,
content,
});
}
console.error(`Loaded ${this.setup.length} setup guide files`);
}
private setupHandlers(): void {
this.server.setRequestHandler(ListToolsRequestSchema, async () => {
const tools: Tool[] = [
{
name: "search_components",
description:
"Search for Modus Web Components by name or keyword. Returns a list of matching components with brief descriptions.",
inputSchema: {
type: "object",
properties: {
query: {
type: "string",
description:
"Search query (component name, keyword, or feature)",
},
},
required: ["query"],
},
},
{
name: "get_component_docs",
description:
"Get the complete documentation for a specific Modus Web Component including attributes, events, and usage examples.",
inputSchema: {
type: "object",
properties: {
component: {
type: "string",
description:
'The component name (e.g., "button", "card", "modal")',
},
},
required: ["component"],
},
},
{
name: "list_all_components",
description:
"List all available Modus Web Components with their categories.",
inputSchema: {
type: "object",
properties: {},
},
},
{
name: "find_by_attribute",
description:
"Find components that have a specific attribute or property.",
inputSchema: {
type: "object",
properties: {
attribute: {
type: "string",
description:
'The attribute name to search for (e.g., "disabled", "color", "size")',
},
},
required: ["attribute"],
},
},
{
name: "get_design_rules",
description:
"Get specific design rules for Modus Web Components (colors, icons, spacing, typography, etc.).",
inputSchema: {
type: "object",
properties: {
category: {
type: "string",
description:
'The design rule category (e.g., "colors", "icons", "spacing", "typography", "breakpoints", "radius_stroke")',
},
},
required: ["category"],
},
},
{
name: "search_design_rules",
description: "Search across all design rules by keyword or term.",
inputSchema: {
type: "object",
properties: {
query: {
type: "string",
description:
'Search query for design rules (e.g., "primary color", "icon size", "spacing scale")',
},
},
required: ["query"],
},
},
{
name: "list_design_categories",
description: "List all available design rule categories.",
inputSchema: {
type: "object",
properties: {},
},
},
{
name: "get_setup_guide",
description:
"Get setup instructions for HTML or React projects using Modus Web Components.",
inputSchema: {
type: "object",
properties: {
type: {
type: "string",
description: 'The setup type ("html", "react", "testing")',
},
},
required: ["type"],
},
},
{
name: "get_theme_usage",
description:
"Get theme implementation guidelines and usage instructions.",
inputSchema: {
type: "object",
properties: {},
},
},
{
name: "get_development_rules",
description:
"Get universal development rules and best practices for Modus Web Components.",
inputSchema: {
type: "object",
properties: {},
},
},
];
return { tools };
});
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
try {
switch (name) {
case "search_components":
return await this.searchComponents((args?.query as string) || "");
case "get_component_docs":
return await this.getComponentDocs(
(args?.component as string) || ""
);
case "list_all_components":
return await this.listAllComponents();
case "find_by_attribute":
return await this.findByAttribute(
(args?.attribute as string) || ""
);
case "get_design_rules":
return await this.getDesignRules((args?.category as string) || "");
case "search_design_rules":
return await this.searchDesignRules((args?.query as string) || "");
case "list_design_categories":
return await this.listDesignCategories();
case "get_setup_guide":
return await this.getSetupGuide((args?.type as string) || "");
case "get_theme_usage":
return await this.getThemeUsage();
case "get_development_rules":
return await this.getDevelopmentRules();
default:
throw new Error(`Unknown tool: ${name}`);
}
} catch (error) {
const errorMessage =
error instanceof Error ? error.message : String(error);
return {
content: [{ type: "text", text: `Error: ${errorMessage}` }],
isError: true,
};
}
});
}
private async searchComponents(query: string): Promise<any> {
const normalizedQuery = query.toLowerCase();
const results: Array<{
component: string;
filename: string;
relevance: string;
}> = [];
for (const doc of this.docs) {
const content = doc.content.toLowerCase();
const componentName = doc.component.toLowerCase();
if (
componentName.includes(normalizedQuery) ||
content.includes(normalizedQuery)
) {
// Extract the first paragraph or description
const lines = doc.content.split("\n");
let description = "";
for (const line of lines) {
if (
line.trim() &&
!line.startsWith("#") &&
!line.startsWith("Tag:")
) {
description = line.trim();
break;
}
}
results.push({
component: doc.component,
filename: doc.filename,
relevance: description || "Modus Web Component",
});
}
}
if (results.length === 0) {
return {
content: [
{
type: "text",
text: `No components found matching "${query}". Try searching for common UI elements like "button", "input", "modal", "card", etc.`,
},
],
};
}
const resultText = results
.map((r) => `**${r.component}**\n${r.relevance}\n`)
.join("\n");
return {
content: [
{
type: "text",
text: `Found ${results.length} component(s) matching "${query}":\n\n${resultText}`,
},
],
};
}
private async getComponentDocs(component: string): Promise<any> {
const normalizedComponent = component
.toLowerCase()
.replace("modus-wc-", "");
const doc = this.docs.find(
(d) => d.component.toLowerCase() === normalizedComponent
);
if (!doc) {
const availableComponents = this.docs.map((d) => d.component).join(", ");
return {
content: [
{
type: "text",
text: `Component "${component}" not found.\n\nAvailable components: ${availableComponents}`,
},
],
};
}
return {
content: [
{
type: "text",
text: doc.content,
},
],
};
}
private async listAllComponents(): Promise<any> {
const componentsByCategory: Record<string, string[]> = {};
for (const doc of this.docs) {
// Extract category from content
const categoryMatch = doc.content.match(/Category:\s*([^\n]+)/i);
const category = categoryMatch ? categoryMatch[1].trim() : "Other";
if (!componentsByCategory[category]) {
componentsByCategory[category] = [];
}
componentsByCategory[category].push(doc.component);
}
let resultText = `# Modus Web Components (${this.docs.length} components)\n\n`;
for (const [category, components] of Object.entries(
componentsByCategory
).sort()) {
resultText += `## ${category}\n`;
resultText += components
.sort()
.map((c) => `- ${c}`)
.join("\n");
resultText += "\n\n";
}
return {
content: [
{
type: "text",
text: resultText,
},
],
};
}
private async findByAttribute(attribute: string): Promise<any> {
const normalizedAttribute = attribute.toLowerCase();
const results: Array<{ component: string; context: string }> = [];
for (const doc of this.docs) {
const lines = doc.content.split("\n");
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
const lowerLine = line.toLowerCase();
// Look for attribute definitions like: - **`disabled`**
if (
lowerLine.includes(`\`${normalizedAttribute}\``) &&
(line.startsWith("-") || line.startsWith("•"))
) {
// Get context - the attribute definition and its properties
const contextStart = i;
let contextEnd = i + 1;
// Include lines until we hit another attribute or empty line
while (
contextEnd < lines.length &&
!lines[contextEnd].match(/^-\s+\*\*`/) &&
contextEnd < i + 10
) {
if (lines[contextEnd].trim() === "") {
break;
}
contextEnd++;
}
const context = lines.slice(contextStart, contextEnd).join("\n");
results.push({
component: doc.component,
context: context.trim(),
});
break;
}
}
}
if (results.length === 0) {
return {
content: [
{
type: "text",
text: `No components found with attribute "${attribute}".`,
},
],
};
}
const resultText = results
.map((r) => `**${r.component}**\n\`\`\`\n${r.context}\n\`\`\`\n`)
.join("\n");
return {
content: [
{
type: "text",
text: `Found ${results.length} component(s) with attribute "${attribute}":\n\n${resultText}`,
},
],
};
}
private async getDesignRules(category: string): Promise<any> {
const normalizedCategory = category.toLowerCase();
const rule = this.rules.find(
(r) =>
r.category.toLowerCase() === normalizedCategory ||
r.filename.toLowerCase().includes(normalizedCategory)
);
if (!rule) {
const availableCategories = this.rules.map((r) => r.category).join(", ");
return {
content: [
{
type: "text",
text: `Design rule category "${category}" not found.\n\nAvailable categories: ${availableCategories}`,
},
],
};
}
return {
content: [
{
type: "text",
text: rule.content,
},
],
};
}
private async searchDesignRules(query: string): Promise<any> {
const normalizedQuery = query.toLowerCase();
const results: Array<{
category: string;
filename: string;
relevance: string;
}> = [];
for (const rule of this.rules) {
const content = rule.content.toLowerCase();
const categoryName = rule.category.toLowerCase();
if (
categoryName.includes(normalizedQuery) ||
content.includes(normalizedQuery)
) {
// Extract the first meaningful line as description
const lines = rule.content.split("\n");
let description = "";
for (const line of lines) {
if (line.trim() && !line.startsWith("#") && !line.startsWith("---")) {
description = line.trim();
break;
}
}
results.push({
category: rule.category,
filename: rule.filename,
relevance: description || "Design rule documentation",
});
}
}
if (results.length === 0) {
return {
content: [
{
type: "text",
text: `No design rules found matching "${query}". Try searching for terms like "color", "icon", "spacing", "typography", etc.`,
},
],
};
}
const resultText = results
.map((r) => `**${r.category}**\n${r.relevance}\n`)
.join("\n");
return {
content: [
{
type: "text",
text: `Found ${results.length} design rule(s) matching "${query}":\n\n${resultText}`,
},
],
};
}
private async listDesignCategories(): Promise<any> {
let resultText = `# Modus Design Rules (${this.rules.length} categories)\n\n`;
for (const rule of this.rules.sort((a, b) =>
a.category.localeCompare(b.category)
)) {
// Extract brief description from content
const lines = rule.content.split("\n");
let description = "Design guidelines and specifications";
for (const line of lines) {
if (
line.trim() &&
!line.startsWith("#") &&
!line.startsWith("---") &&
line.length > 10
) {
description =
line.trim().substring(0, 100) + (line.length > 100 ? "..." : "");
break;
}
}
resultText += `## ${rule.category}\n${description}\n\n`;
}
return {
content: [
{
type: "text",
text: resultText,
},
],
};
}
private async getSetupGuide(type: string): Promise<any> {
const normalizedType = type.toLowerCase();
const guide = this.setup.find(
(s) =>
s.setupType.toLowerCase() === normalizedType ||
s.filename.toLowerCase().includes(normalizedType)
);
if (!guide) {
const availableTypes = this.setup.map((s) => s.setupType).join(", ");
return {
content: [
{
type: "text",
text: `Setup guide type "${type}" not found.\n\nAvailable types: ${availableTypes}`,
},
],
};
}
return {
content: [
{
type: "text",
text: guide.content,
},
],
};
}
private async getThemeUsage(): Promise<any> {
const themeGuide = this.setup.find(
(s) => s.setupType === "theme" || s.filename.includes("theme")
);
if (!themeGuide) {
return {
content: [
{
type: "text",
text: "Theme usage guide not found. Please run: node download-docs.js",
},
],
};
}
return {
content: [
{
type: "text",
text: themeGuide.content,
},
],
};
}
private async getDevelopmentRules(): Promise<any> {
const universalGuide = this.setup.find(
(s) => s.setupType === "universal" || s.filename.includes("universal")
);
if (!universalGuide) {
return {
content: [
{
type: "text",
text: "Universal development rules not found. Please run: node download-docs.js",
},
],
};
}
return {
content: [
{
type: "text",
text: universalGuide.content,
},
],
};
}
async run(): Promise<void> {
const transport = new StdioServerTransport();
await this.server.connect(transport);
console.error("Modus Web Components MCP Server running on stdio");
}
}
const server = new ModusDocsServer();
server.run().catch(console.error);